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acc_mode  -  access  mode 

SYNOPSIS 
bits : 

DESCRIPTION 

Acc  mode  describes  the  access  allowed  a  process  to  a  particular  segment 
of  its  current  segment  set.  An  acc  mode  is  composed  of  three  bits  indi¬ 
cating  permission  to  read,  to  write,  and  to  execute.  They  are  equivalent 
to  selected  discretionary  acc  bits.  The  correspondences  are: 


CONST 


readAcc 

writeAcc 

executeAcc 


“  owner  Read; 

“  owner  Write ; 

“  owner  Execute ; 


The  acc  mode  of  a  segment  is  initialized  when  its  segment  is  made  a  part 
of  the  process's  segment  set  using  K  build  segment  or 
K  rendezvous  segment.  The  acc  mode  may  be  changed  using 
K  set  segment  status  or  K  remap .  In  no  case  does  a  segment's  acc  mode 
(which  is  always  in  relation  to  a  process)  allow  more  permissive  access 
than  that  allowed  the  process  by  the  segment's  discretionary  access. 

SEE  ALSO 

K_remap  (II),  K_rendezvous_segaent  (II),  K_set_segwent_status  (II), 
discr_access  (I),  se&_stat_block  (I), 


Accession  For 
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NAME 

compar  t_set  -  set  of  security  compartments 

SYNOPSIS 

bits32: 

DESCRIPTION 

A  maximum  of  32  security  compartments  may  be  used  in  a  KSOS  system.  The 
type  independent  information  (the  tii_struct)  of  every  object  contains  a 
_compart  set  field  that  determines  which  security  compartments  the  object 
belongs  sx>,  with  each  bit  indicating  one  compartment.  A  process  may  not 
read  an  object  if  the  object  belongs  to  any  compartments  which  the  pro¬ 
cess  does  not  belong^rtQ.  A  process  may  not  write  on  an  object  if  the 
process  belongs  to  any  compartments  that  the  object  does  not  belong/fco. 

The  32  compartments  are  given  arbitrarty  names  via  an  enumerated  type  as 
is  shown  below: 


compartments  -  ( 
SYSTEM, 
compar  t_4, 
compart_8, 
compart_12, 
compart_16, 
compart_20, 
compart_24, 
compart_28, 
); 


compart_l, 
compar t_5, 
Conq>art_9, 
compar  t_l 3, 
compar  t_l 7, 
compar t_21f 
compar t_2  5, 
compart_29. 


compar  t_2, 
compart_6, 
compar t_10, 
compar  t_l  4, 
compar  t_l  8, 
compart_22, 
compar  t_2 6, 
compar  t_30. 


compar t_3, 
compar t_7, 
compart_l  1 , 
compar t_l  5, 
compart_19, 
compar  t_23, 
compart_27, 
compar t_31 


SEE 


tii  struct (I) 
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NAME 

discr_access  -  discretionary  access 

SYNOPSIS 
bits : 

DESCRIPTION 

The  discr  access  type  describes  the  discretionary  access  to  Kernel 
objects.  Discretionary  access  is  divided  into  three  sets  of  three  bits 
each.  The  first  set  refers  to  the  object's  owner,  the  next  to  others  in 
the  same  user  group,  and  the  last  to  all  others.  Within  each  set  the 
three  bits  indicate  permission  to  read,  to  write,  and  to  execute.  The 
execute  bits  are  meaningful  only  if  a  process  has  the  privReali2eExecPer- 
mission  privilege.  Each  execute  bit  is  then  equivalent  to  the 
corresponding  read  bit.  Setuid  and  setgid  are  special  bits  used  in  con¬ 
junction  with  the  execute  bits.  When  a  process  image  is  created  from  an 
object  with  the  setuid  bit,  the  owner  of  the  process  is  temporarily 
changed  to  be  the  owner  of  that  object.  Setgid  is  analogous  to  setuid. 
operating  on  group  rather  than  owner. 

The  following  table  contains  the  bit-  definitions  for  the  discretionary 
access  field. 


setuid  10 
setgid  9 

ownerRead  8 
ownerWrite  7 
ownerExecute  6 
groupRead  5 
groupWrite  4 
groupExecute  3 
allRead  2 
allWrite  1 
allExecute  0 


SEE  ALSO 

K  build  segment  (II),  K  creat  (II),  K  set  da  (II),  priv  (I) 
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NAME 

file_stat_block  -  file  status  block 
SYNOPSIS 

file  stat  block  -  RECORD 


f  size 
subtype 
time  last  mod 
open  at  crash 

END; 

DESCRIPTION 


:  cardina!32; 
:  seid; 

;  cardina!32; 
:  boolean 


The  file  status  block  is  used  to  return  information  about  files,  termi¬ 
nals,  extents  and  devices. 

F_size  is  the  number  of  characters  in  the  file.  The  kernel  keeps 

internal  track  of  the  highest  block  number  written  in  the 
file.  The  K  device  function  SETFILESIZE  can  also  be  used 
to  set  this  field. 

Subtype  is  the  Seid  of  the  subtype  of  the  I/O  object  or  the  null 

seid  if  the  object  is  not  subtyped. 

Time_last_mod  is  the  time  of  last  modification  of  the  text  of  a  file. 

It  is  represented  as  the  number  of  ticks  since  January  1, 
1980.  This  time  is  only  updated  on  K  open  and  K  close  if 
the  open  mode  allows  write  access.  For  all  I/O  objects 
other  than  files,  this  value  is  zero. 

Open_at_crash  is  true  if  the  file  was  open  for  writing  when  the  system 
crashed.  The  next  open  for  writing  will  clear 
open  at  crash.  The  file  system  recovery  program(s)  should 
be  run  on  all  files  with  this  field  set.  For  non-file 
objects,  open  at  crash  is  always  false.  It  should  be 
noted  that  when  open  at  crash  is  true,  f  size  may  be 
incorrect. 

SEE  ALSO 

K _jget_file_status  (II),  K_device_function  (II),  Seid  (I) 


integrity_cat_type (I ) 


KSOS  1/6/81 


integrity_cat_type (I ) 


NAME 

integrity_cat_type  -  integrity  categories 
SYNOPSIS 

integrity  cat  type  -  ( 
integrity  cat  2. 
integrity  cat  5. 
integrity  cat  8, 
integrity  cat  11. 
integrity  cat  14. 

DESCRIPTION 

There  are  a  16  possible  integrity  categories  on  a  KSOS  system-  These 
categories  are  defined  in  the  integrity  cat  type  enumerated  type.  The 
integrity  categories  form  an  ordered  set  which,  along  with  the  security 
category  and  security  compartments,  control  access  to  and  from  the 
objects  of  the  system-  If  object  A  has  a  higher  integrity  category  than 
object  B  then: 


A  cannot  read  B 

A  can  write  B 

B  can  read  A 

B  cannot  write  A 


integrity  cat  0. 
integrity  cat  3. 

integrity  cat  6. 
integrity  cat  9. 

integrity  cat  12. 
integrity  cat  15 


integrity  cat  1. 
integrity  cat  4. 
integrity  cat  7. 
integrity  cat  10, 
integrity  cat  13. 

); 


SEE 

compar t_set (I )  security_cat_type (I ) 
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INTRODUCTION  TO  KERNEL  INTERFACE  TYPES 

Section  I  of  this  manual  describes  all  the  types  used  by  the  Kernel  Call 
Interface  (section  II).  The  kernel  types  defined  in  the  interface  are  com¬ 
posed  of  7  different  basic  types  and  3  structure  types.  All  the  kernel  type 
definitions  are  built  from  these  types.  Understanding  these  types  is  essen¬ 
tial  for  using  and  building  future  kernel  call  interfaces. 

char  is  an  eight  bit  unsigned  quantity.  It  is  used  to  represent 

variables  with  up  to  256  distinct  values.  A  char  field  must 
be  and'ed  with  a  377(8)  mask  when  converted  to  a  16  bit 
quantity  because  of  the  PDP-11  hardware  sign  extension  on 
byte  to  word  data  transfer  instructions. 

boolean  is  also  an  eight  bit  quantity.  A  boolean  variable  may  have 
one  of  two  values  -  true  or  false  The  false  value  is  defined 
always  to  be  zero.  The  true  value  is  any  nonzero  value. 

bits  is  a  16  bit  quantity.  The  bits  are  numbered  right  to  left 

starting  with  zero  (i-e.  bit  0  is  the  rightmost  (  least  sig¬ 
nificant)  bit). 

bits32  as  suggested  by  its  name,  is  32  bits  long.  However,  the 

bits  are  numbered  left  to  right  starting  with  zero  (i.e., 
bit  0  is  the  leftmost  (most  significant)  bit).  If  bits32  is 
accessed  as  an  array  of  bits .  a[0]  contains  bits  0  through 
15  and  a[l]  contains  bits  16  to  31. 

integer  is  a  16  bit  signed  quantity  in  two's  complement  notation. 

Cardinal  is  a  16  bit  unsigned  quantity  in  two's  binary  notation. 

cardina!32  is  a  32  bit  unsigned  quantity.  If  cardina!32  is  accessed  as 

an  array  of  cardinal.  a(0]  contains  the  high  order  word  and 
a[l]  contains  the  low  order  word. 

The  structured  types  are  used  to  build  data  structures  from  the  basic 
types.  The  structured  types  are  enumerations,  records  and  arrays. 

Enumerations  An  enumeration  is  a  list  of  identifiers  which  denote  the 

values  constituting  a  data  type.  These  identifiers  may  be 
used  as  constants  in  programs.  They,  and  no  other  values, 
belong  to  the  enumerated  type.  An  ordering  relation  is 
defined  on  these  values  by  their  sequence  in  the  enumera¬ 
tion. 

Records  A  record  structure  consists  of  a  number  of  components 

where  each  component  is  identified  by  a  unique  field  iden¬ 
tifier.  Field  identifiers  are  known  only  within  the 
record  structure  definition  and  within  field  designators, 
i.e.,  when  they  are  preceded  by  a  qualifying  record  vari¬ 
able  identifier. 
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Arrays 


An  array  structure  consists  of  a  number  of  components. 
Each  component  is  identified  by  a  number  of  indices  whose 
range  is  specified  in  the  declaration  of  the  array  struc¬ 
ture. 


SEE  ALSO 


Modula  Specifications,  NEWcalls.mod 
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NAME 

ioStatus  -  Status  of  I/O  operation 

SYNOPSIS 

ioStatus  “  RECORD 

devlndep;  K  err  num; 
devDep  :  bits 

END; 

DESCRIPTION 

devlndep  contains  the  device  independent  status  upon  completion  of  an 
I/O  operation*  The  status  returned  is  one  of  the  Kernel's 
exception  numbers. 

devDep  contains  the  device  dependent  status  upon  completion  of  an 

I/O  operation.  This  field  is  only  defined  for  special  dev¬ 
ices,  such  as  the  network  devices,  which  have  peculiar  pro¬ 
perties. 

SEE  ALSO 

K_device_f unction  (II),  K_read  (II),  KjWTite  (II),  K_err_num  (I) 
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NAME 

ipc_block  -  inter-process  communication  messages 

SYNOPSIS 

msg  limit  -  11; 

msg  struct  “  ARRAY  0:mag  limit  OF  char; 

ipc  block  -  RECORD 

ipc  seid:  seid; 
ipc  msg  ;  msg  struct 

END; 

DESCRIPTION 

An  ipc  block  is  the  general  form  for  all  the  different  types  of  inter¬ 
process  communication  messages  (e.g*  signals  and  IPC's).  Messages  can  be 
generated  by  the  kernel,  by  your  process  or  by  other  processes. 

The  ipc  seid  contains  the  seid  of  the  process  which  sent  the  ipc  block. 

The  ipc  msg  contains  the  text  of  the  ipc_block. 

The  first  byte  of  the  ipc_msg,  by  convention,  is  the  event  type.  This 
field  and  the  ipc  seid.  determines  the  message  type.  The  following  event 
types  are  predefined  and  can  not  be  used  for  other  purposes.  All  other 
event  type  numbers  can  be  used  by  cooperating  processes  as  they  wish. 

null_event  0 

memerr__event  1 

bpt_event  2 

iot_event  3 

cpuerror_event  4 

illinst_event  5 

mm_event  6 

fltpnt_event  7 

ttoggle_event  10 

talarm_event  11 

emulcall_event  12 

iocomplete_event  13 

Kernel  Generated  Messages 

This  type  of  message  can  only  be  generated  by  the  kernel*  These  messages 
always  come  through  the  hardware  pseudo  interrupt-channel.  The  seid 
field  contains  the  Kernel  Seid.  The  event  type  must  be  one  of  the  fol¬ 
lowing  : 


memory  error 

break  point  trap  instruction 
input  output  trap  instruction 
cpu  error 

illegal  instruction 
memory  management 
floating  point  processor 
timer  toggle 
timer  alarm 
emulator  call 
I/O  completion 


memerr_event 
bpt_event 
iot  event 


-  1  - 


ipc_block(I) 


KSOS  1/6/81 


ipc_block(I) 


cpuerror_event 

illinst_event 

mm_event 

£ltpnt_event 

The  time  of  the  pseudo-interrupt  is  placed  in  the  last  four  bytes  of  the 
ipc  msg. 

The  floating  point  processor  message  also  has  its  status  register  stored 
in  bytes  2  and  3  of  the  ipc  msg. 

Messages  on  the  Behalf  of  Tour  Process 

These  messages  can  only  be  generated  by  some  action  to  or  by  your  pro¬ 
cess. 

The  seid  field  contains  the  Kernel  Seid  except  I/O  completion  which  con¬ 
tains  the  process  Seid*  Messages  of  this  type  have  the  following  event 
types: 


ttoggle_event 

talarm_event 

emulcall_event 

iocomplete_event 

The  timer  and  I/O  completion  come  through  their  respective  pseudo¬ 
interrupt  vectors.  The  emulator  Call  pseudo-interrupts  through  at  base 
level.  This  pseudo-interrupt  will  occur  no  matter  what  the  pseudo¬ 
interrupt  level  is  set  at. 

The  emulator  call  message  occurs  synchronously  when  your  process  requests 
them.  An  I/O  completion  message  occurs  asynchronously  after  your  process 
initiates  an  I/O  requesting  such  a  message.  The  timer  messages  can  be 
Caused  either  by  your  process  or  by  another  process  setting  the  timer 
related  fields  in  the  process  status  block. 

The  last  four  bytes  of  both  the  timer  messages  and  the  emulator  call  con¬ 
tain  the  time  that  the  pseudo  interrupt  occurred. 

The  I/O  completion  message  has  the  following  structure: 


RECORD 

event_type 

stat 

byteCount 

async 

filler 

END; 


char ; 
ioStatus 
cardinal; 
cardinal; 

ARRAY  1:2  OF  char; 


where  : 
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stat.devlndep  contains  the  device  independent  completion  status.  This 
field  is  valid  for  all  I/O  completion  messages* 

stat.devDep  contains  the  device  dependent  completion  status.  This 

field  is  valid  only  for  special  devices.  The  meaning  of 
this  field  can  be  found  with  the  supported  device  manual 
pages. 

byteCount  is  the  number  of  characters  transferred  by  this  asynchro¬ 
nous  request. 

async  is  the  user  supplied  asynchronous  identifier. 

Messages  generated  by  Processes 

Messages  of  this  type  are  sent  using  K  tignal  or  K  post  and  are  received 
either  through  the  pseudo  interrupt  vectors  or  by  K  receive.  The  seid 
field  contains  the  sending  process  seid.  The  ipc  mag  record  can  contain 
anything.  By  convention,  the  first  byte  contains  the  event  type. 

SEE  ALSO 

ioStatus  (I),  Seid  (I),  Pseudo  Interrupts  (I),  K_post  (II),  K_signal 
(II),  K_receive  (II) 
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NAME 

K_err_num  -  Kernel  error  numbers 

SYNOPSIS 

cardinal : 


DESCRIPTION 

This  list  of  Kernel  error  numbers  is  subject  to  revision  pending  resolu¬ 
tion  of  discrepancy  reports  concerning  them.  The  actual  numerical  value 


each  exception  may  be 

found  in  NEWcalls .mod . 

related  Kernel  calls 

and  the  exception  values  they  return  follow: 

XOK 

No  exception 

XKemt 

kernel  generated  EMT 

XMapPr 

bad  mapping  process 

Xaborted 

I/O  request  was  aborted 

XasynC 

asynchronous  I/O  initiated 

XatEot 

OK  but  tape  is  now  after  EOT 

Xattn 

secure  attention  char  input 

XbAddr 

bad  address 

XbEmt 

bad  emt 

XbFn 

^  bad  function  code 

XbLcArgSg 

bad  location  for  arg  seg 

XbMapIn 

Cannot  map  in  PCS 

XbMapOut 

Cannot'  map  out  PCS 

XbMovIn 

bad  PCS  move  in 

XbMovO 

bad  PCS  move  out 

XbNoMes 

No  message 

XbParam 

bad  Kernel  interface  param 

XbPcsRef 

bad  PCS  reference 

XbPcsSd 

bad  PCS  seid 

Kb  Pm 

XbPrSd 

bad  process  seid 

XbPsLev 

bad  pseudo  interrupt  level 

XbSchL 

bad  scheduler  action 

XbSgDes 

bad  seg  des 

XbSgRng 

bad  seg  range 

XbSgSd 

bad  seg  seid 

XbSgSz 

seg  size  is  not  mult  of  512 

Kb St Pm 

bad  status  parameter 

XbSwp 

bad  PCS  swap 

XbSz 

bad  size  parameter 

XbSzArgSg 

bad  size  for  arg  seg  (too  large) 

KbTiiPm 

bad  tii  parameter 

KbadBlockNo 

bad  block  number  on  I/O 

XbadDa 

SMXdap  failure 

XbadFs 1 

1:  did  not  find  expected  slot  kind 

XbadFs2 

2:  bad  checksum  in  slot 

XbadFs 3 

3:  reserved 

XbadLink 

K_link  overflowed  count  (LEAK) 

XbadModes 

illegal  combination  of  open  modes 

1 
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XbadNsp 

XbadOd 

XbadPriv 

XbadRef  Count 

XbadSize 

XbadSlot 

XbadStCap 

XbadSubtype 

Xb ad S ub t yp eMa t ch 

XbadVol 

XbdDm 

XbdKcl 

XblAdVacMmu 

XblNtlnSg 

XbpT 

Xbusy 

XcPsInt 

XchglDspc 

XchgSgOwn 

XcpuT 

XcritExcl 

XdapViol 

Xdown 

XdupSg 

Xempty 

XendOf File 

Xerror 

XexFile 

XexSpace 

Xfault 

XfloT 

XiiT 

XinBuf 

XinSgAldMap 

XindMap 

XioT 

Xmark 

XmemT 

XmmT 

Xmoving 

XmtSpaCe 

XnPgSg 

XnPvLkSg 

XnPvStkSg 

XnSgDes 

XaWrtArgSg 

XncnDo 

XnoAcc 

XnoAsync 

XnoClass 

XnoExclWrite 

XnoFile 

XnoFunct 


invalid  size  in  pBlock 
bad  upt  slot 


unacknowledged  disk  volume 

bad  domain 

bad  Kernel  Call 

block  addr  has  vacant  page  reg 

block  not  in  seg 

break  point  trap 

Exclusive  use  fails  because  busy 

cannot  pseudo  interrupt 

attempt  to  change  I/D  space  of  seg 

attempt  to  change  owner  of  seg 

cpu  error 


Hardware  is  now  down 

attempt  to  duplicate  use  of  a  seg 

empty  upt  slot 

read  would  pass  end  of  file 

Retry able  hardware  error 

Exclusive  open  on  fork  attempt 

extent  table  full  (LEAK) 

Non-retryable  hardware  error 

floating  point  unit  trap 

illegal  instruction 

Input  buffer  illegal  for  fn 

incoming  seg  already  mapped 

bad  mapping  index 

I/O  trap 

EOF  mark  read  from  magnetic  tape 

memory  error 

memory  management  trap 

offline  motion  (rewind)  going 

mount  table  full  (LEAK) 

seg  does  not  cross  page  boundary 

no  priv  to  set  mem_lock  (swappable) 

no  priv  to  set  swap_lock  (sticky) 

not  a  seg  des  (out  of  range) 

non-writable  arg  seg 

cannot  say  why 

no  access 

asynchronous  queue  full  (LEAK) 
Object  wrong  class  for  this  call 


Hardware  does  not  support  this  fn 
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no  swap  help  possible 
mapping  process  not  init 
no  existing  map 
No  open  mode  given 
object  non-existent 

does  not  have  privilege 
no  more  process  allowed 
no  privSetLevel 
no  privSetPriv 
No  file  system  space  left 

tranquility  violation 
Object  not  open  for  reading 

non-writable  outgoing  segment 

Global  open  table  full  (LEAK) 
outgoing  seg  already  unmapped 
POST  exhausted 

privileged  function  not  allowed 
seg  mapped  when  setting  acc.loc 
seg  no  access 
seg  swapped  out 
seg  is  sharable 
bad  PCS  slot  allocation 
Hardware  did  not  respond  in  time 
cannot  interrupt  for  K_signal 
virtual  memory  conflict 
attempt  to  make  write-only  seg 
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Ik 


NAME 

openDescriptor  -  open  file  handle 


SYNOPSIS 


integer; 


DESCRIPTION 

OpenDescriptors  are  used  to  reference  open  objects  in  the  various  I/O 
Kernel  calls.  When  a  K  create  or  a  K  open  is  done,  an  openDescriptor  is 
returned . 


SEE  ALSO 

K__close  (II),  K_create  (II),  K_device_f unction  (II),  K_get_file_status 
(II),  K_open  (II),  K_read  (II),  K_set_f ile_status  (II),  K_write  (II) 
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NAME 

openModes  -  open  inodes 
SYNOPSIS 

openModes  "  RECORD 

read  :  boolean; 

vrite  ;  boolean; 

exclusive  read  ;  boolean; 
exclusive  write  :  boolean 

END; 

DESCRIPTION 

The  OpenModes  record  is  used  to  indicate  the  mode  in  which  an  object  is 
to  be  opened  or  created-  The  list  below  describes  each  field- 


read  when  true,  indicates  that  the  object  should  be  opened  or 

created  for  reading. 

when  true,  indicates  that  the  object  should  be  opened  or 
created  for  writing- 

when  true,  indicates  that  the  object  should  be  opened  or 
created  for  reading  by  the  calling  process  only. 

exclusive_write  when  true,  indicates  that  the  object  should  be  opened  or 
created  for  writing  by  the  calling  process  only. 

The  only  valid  combinations  of  open  modes  fields  are: 

exclusive 


mm 

read 

write 

read 

write 

true 

false 

false 

false 

Normal  read. 

ham 

false 

true 

false 

false 

Normal  vrite. 

true 

true 

false 

false 

Normal  read  and  write- 

true 

true 

false 

true 

Lock  out  all  other  writers 

mm 

true 

true 

Lock  out  everybody  else- 

write 

exclusive  read 


All  other  combinations  are  invalid. 


SEE  ALSO 

K_creat  (II), 


K_open  (II) 
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NAME 

pjblock  -  parameter  block 
SYNOPSIS 

RECORD 

location:  virt  loc: 
b  size  :  cardinal: 

END; 

DESCRIPTION 

P  block  contains  the  I/O  buffer  description, 
location  is  the  virtual  location  of  the  I/O  buffer. 

b_size  is  the  byte  size  of  the  I/O  buffer. 

SEE  ALSO 

virt_loc  (I),  K_device_f unction  (II).  K_read  (II),  Rewrite  (II) 


block (I) 
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NAME 

priv_struct  -  set  of  privileges 

STOOPSIS 

bits32: 

DESCRIPTION 

Each  bit  corresponds  to  a  privilege  in  the  priv  names  enumeration.  See 
the  B-5  specifications  for  the  meaning  of  the  different  privileges. 

priv_names  *  (  (*bit  number*) 


privFileUpdateStatus , 

(* 

00 

*) 

privLink, 

(* 

01 

*) 

privLockSeg, 

(* 

02 

*) 

privModifyPriv, 

(* 

03 

*) 

privMount , 

(* 

04 

*) 

privSetLevel, 

(* 

05 

*) 

privStickySeg, 

(* 

06 

*) 

privSetPath, 

(* 

07 

*) 

privViolSimpSecurity , 

(* 

08 

*) 

privViolStarSecurity, 

(* 

09 

*) 

privViol Simp Integrity, 

(* 

10 

*) 

privViolStar Integrity, 

(* 

11 

*) 

privViolDiscr Access , 

(* 

12 

*) 

p  rivReal izeExecPer miss ion , 

(* 

13 

*) 

privSignal, 

(* 

14 

*) 

privWalkPTable , 

(* 

15 

*) 

privHalt, 

(* 

16 

*) 

privKernelCall , 

(* 

17 

*) 

privViolCompartments , 

(* 

18 

*) 

privSetComm, 

(* 

19 

*) 

privlmmigrate , 

(* 

20 

*) 

p  r  i  v  Vio  ITr  an  qui  1  it  y 

(* 

21 

*) 

); 


SEE  ALSO 

K_set_priv  (II) 
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NAME 

pseudo_int_vector  -  pseudo-interrupt  vector 
STOOPSIS 

pseudo  int  vector  «  RECORD 
interrupted  pt 
interrupted  ps 
interrupted  p  level 
int  mag 
new  pc 
new  ps 

END; 

DESCRIPTION 

interrupted_pc 

pc  of  process  when  (before)  pseudo-interrupt  asserted 

inter rupted_ps 

ps  of  process  when  (before)  pseudo-interrupt  asserted 
inter rupted_p_level 

pseudo-interrupt  level  of  process  when  (before)  pseudo¬ 
interrupt  asserted 

intjnsg  pseudo-interrupt  message 

new_pc  pc  of  process  after  pseudo-interrupt  asserted 

new_ps  ps  of  process  after  pseudo-interrupt  asserted 


pseudo  interrupt  levels  : 


base_Xev 

■ 

0 

(*  emulator  call 

*> 

ipc_lev 

- 

1 

(*  IPC  pseudo  int 

*) 

time_lev 

- 

2 

(*  timer  pseudo  int 

*) 

sig  lev 

- 

3 

(*  K_signal  pseudo  int 

*) 

io_lev 

m 

4 

(*  I/O  pseudo  int 

*) 

hard_lev 

- 

5 

(*  hardware  pseudo  int 

*) 

:  cardinal: 

:  cardinal: 

:  cardinal; 

:  ipc  block; 
:  cardinal; 

:  cardinal 
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NAME 

proc_3tat_block  -  process  status  block 
STNOPSIS 


aroc  stat  block 


RECORD 


own 

: 

seid: 

parent 

: 

seid: 

family 

• 

cardinal: 

owner 

: 

cardinal: 

group 

• 

cardinal; 

aprio 

cardinal; 

pseint 

cardinal: 

PS. 

cardinal: 

alarm 

cardinal; 

clock 

cardinal32: 

tt 

boolean ; 

s timing 

; 

cardinal ; 

u timing 

; 

cardinal 

END; 


DESCRIPTION 


This  record  contains  process  dependent  information. 

A  fields  with  an  asterisk  by  its  name  is  a  read  only  variable. 

*own  is  the  seid  of  the  process  associated  with  this  status 

block. 


•parent  is  the  seid  of  the  process  which  created  the  process,  named 
by  own 

family  is  the  family  name  controlled  by  the  NKSR.  This  field  may 

only  be  set  by  processes  with  the  privilege  privSetLevel. 

owner  is  the  real  user  identifier.  This  field  may  only  be  set  by 

processes  with  the  privilege  privSetLevel. 

group  is  the  real  group  identifier.  This  field  may  only  be  set  by 

processes  with  the  privilege  privSetLevel. 

aprio  is  the  advisory  priority  of  the  process.  A  process  in  user 

domain  can  set  this  field  between  0  and  63.  A  process  in 
supervisor  domain  can  set  this  field  between  0  and  127.  A 
process  with  privSetLevel  can  set  this  field  between  0  and 
255.  Priority  0  is  the  lowest  priority. 
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pseint  is  the  current  pseudo-interrupt  level  of  the  process. 

ps  is  the  processor  status  word  of  the  process. 

alarm  is  the  value  of  the  real-time  timer  alarm  in  clock  ticks. 

Setting  this  field  activates  the  real-time  timer  which  will 
generate  a  timer  pseudo-interrupt.  Setting  this  field  to 
zero  cancels  the  alarm. 

clock  is  the  value  of  the  time  of  day  clock  in  clock  ticks.  This 

field  is  read-only  except  for  the  Initial  Process. 

tt  is  the  timer  toggle  clock.  Setting  this  field  to  true 

causes  a  timer  toggle  pseudo-interrupt  on  every  clock  tick. 

*stiming  is  the  amount  of  time  spent  in  the  supervisor  domain  in 
clock  ticks . 

*utiming  is  the  amount  of  time  spent  in  the  user  domain  in  clock 
ticks . 


SEE  ALSO 

priv__struct  (I),  seid  (I)  tii_struct  (I),  K_get_process_status  (II), 
K_set_process_status  (II) 
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NAME 

security_cat_type  -  security  categories 
SYNOPSIS 

security  Cat  type 
security  cat  2, 
security  cat  5, 
security  cat  8. 
security  Cat  11. 
security  cat  14, 

DESCRIPTION 

There  are  a  16  possible  security  Categories  on  a  KSOS  system.  These 
categories  are  defined  in  the  security  cat  type  enumerated  type.  The 
security  categories  form  an  ordered  set  which,  along  with  the  integrity 
category  and  security  compartments,  control  access  to  and  from  the 
objects  of  the  system.  If  object  A  has  a  higher  security  category  than 
object  B  then: 


A  Can  read  B 

A  cannot  write  B 

B  cannot  read  A 

B  can  write  A 


SEE 

compar t_set (I ) ,  integrity_cat_type (I ) 


-  (  security  cat  0. 

security  Cat  3. 
security  cat  6. 
security  Cat  9. 

security  cat  12. 
security  Cat  15 


security  Cat  1, 
security  cat  4. 
security  cat  7. 
security  cat  10. 
security  cat  13. 


I 
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NAME 

seid  -  secure  entity  identifier 
SYNOPSIS 

nsp  type  *  char : 

seid  “  RECORD 

nsp  :  nsp  type; 
uniq  idO;  char; 
uniq  idl;  cardinal 

END; 

DESCRIPTION 

A  seid  uniquely  identifies  each  ksos  object-  A  seid  has  two  fields,  the 
name  space  partition  (nsp)  and  a  24  bit  field.  Each  kernel  object  class 
is  given  its  own  nsp-  The  24  bit  field  is  used  to  identity  the  indivi¬ 
dual  instances  of  the  kernel  object-  (This  field  is  subdivided  into 
uniq  ido  and  unil  idi  pieces.) 

The  following  table  contains  the  valid  name  space  partitions. 


null_nsp 

0 

null 

extent_nsp 

1 

extents 

terminal_nsp 

2 

terminal 

device_nsp 

3 

devices 

process_nsp 

4 

processes 

segment_nsp 

5 

segments 

subtype_nsp 

6 

subtypes 

kerne  l_nsp 

7 

kernel 

same_nsp 

128 

reserved  for  directories 

root_nsp 

129 

ROOT  file  system 

low_file_nsp 

129 

lower  limit  on  file  system 

high_file_nsp 

255 

upper  limit  on  file  system 

The  root  file  system  has  the  distinguished  value  of  129.  All  other  file 
systems  have  nsp  values  from  130  to  255,  which  are  returned  by  the  kernel 
when  the  file  system  is  mounted. 

The  description  given  is  sufficient  for  all  users  except  system  program¬ 
mers.  The  24  bit  quantity  has  many  different  fields  discriminated  by  the 
nsp. 


Null  Seid 

The  null  seid  is  a  distinguished  value.  Uniq  idO  and  uniq  idl  have 
values  of  zero.  In  general  the  null  seid  acts  as  a  place  holder.  The 
null  seid  is  always  translated  by  the  kernel  interface  to  be  the  seid  of 
the  calling  process. 
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Process  Seid 

Each  process  has  a  seid  which  is  valid  for  the  life  of  the  process. 

Uniq  idO  contains  the  process  table  index.  Pniq  idl  contains  a  random 
number  to  make  the  process  seid  unique  over  some  period  of  time. 

Segment  Seid 

Each  segment  has  a  seid  which  is  valid  for  the  life  of  the  segment. 

Pniq  idO  contains  the  global  segment  table  index,  while  uniq  idl  contains 
a  random  number  to  make  the  segment  seid  unique  over  some  period  of  time. 

Kernel  Seid 

The  kernel  seid  is  a  distinguished  value  used  to  identify  messages  sent 
by  the  kernel.  Both  uniq  idO  and  uniq  idl  contain  zero  values. 

Device  Seid 

Each  device  has  a  seid  which  is  valid  for  the  life  of  KSOS.  Changing 
these  seids  will  cause  compatibility  problems  between  KSOS  systems. 

Pniq  idO  contains  the  device  class.  The  device  class  identifies  the  type 
of  device  being  used.  The  following  device  class  assignments  nave  been 
made. 


disks  1-9 

tapes  11-19 

asynchronous  communication  devices  21-29 

synchronous  communication  devices  31-39 

network  communications  devices  41-49 

paper  tape  devices  51-59 

card  readers  61-69 

printers  71-79 


The  following  device  class  numbers  have  been  assigned  to  the  following 
devices . 


disks 

RK05 

1 

RWP04 

2 

RWP05 

3 

PWP06 

4 

RWS04 

5 

tapes 

TWE16 

11 

TM1 1 

12 

TP  56 

13 

network 

IMP  1  IB 

41 

LHDH 

42 

paper  tape 

PRU 

51 

PC11 

52 

printers 

LP1 1 

71 

Pniq  idl  distinsuishes 

multiple  devices 

of  the  same  type.  The  first 

ice  has  a  value  of  zero  and  all 

the  rest 

are  numbered 

sequentially. 

field  can  not  be  greater  than  256. 
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Extent  Seid 

All  block  addressable  devices  contain  extents.  Each  extent  has  its  own 
seid.  For  each  device,  the  first  four  extents  are  predefined  across  all 
KSOS  systems.  Uniq  idO  is  the  same  as  uniq . idO  on  the  device  Seids  for 
the  device  upon  which  the  extent  rides.  Uniq  idl  however,  has  the  low 
order  byte  containing  Uniq  idl  of  the  device  seid.  The  high  order  byte 
contains  the  extent  number , 


Subtype  Seid 

The  subtype  seids  are  valid  across  all  KSOS  systems.  Subtype  seids  are 
always  predefined.  The  following  subtype  seids  have  been  defined. 


seid 


uniq_idO 


uniq_idl 


UNIX  directory 
KSOS  file  system 
Network  Files 


100  0 
100  1 
100  2 


Terminal  Seid 

Each  terminal  has  a  seid  which  is  valid  across  all  KSOS  systems.  Two 
types  of  terminal  devices  are  supported,  the  DL  and  DH.  DL  devices  have 
uniq  idO  values  of  0  through  49.  The  value  of  0  is  reserved  for  the  con¬ 
sole  device.  DH  devices  have  their  uniq  idO  starting  with  50.  Uniq  idl 
is  always  the  terminal  path  number.  The  path  number  is  assigned  each 
time  a  user  changes  to  a  new  level  by  the  NKSR.  The  path  numbers  0  and  1 
are  reserved  for  the  secure  server  and  the  secure  services  respectively. 

File  Seid 

A  file  has  a  seid  which  is  valid  for  the  life  of  the  file.  The  nsp  indi¬ 
cates  which  file  system  the  file  is  on.  The  uniq  idO  and  uniq  idl  fields 
contain  the  file's  24  bit  Jnode  number. 
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NAME 

seg  stat  block  -  segment  status  block 


SYNOPSIS 

seg  stat  block  ”  RECORD 


END; 


mem  lock 
mem  advise 
swap  lock 
sharable 
growth 
stat  size 
stat  seld 
stat  des 
stat  mapped 
stat  acc 
stat  loc 


:  boolean ; 

:  boolean ; 

:  boolean; 

:  boolean ; 

:  direction; 
:  seg  size; 
seid ; 

:  seg  des; 

:  boolean; 

:  acc  mode; 

:  virt  loc; 


DESCRIPTION 


Fields  marked  with  an  asterisk  (*)  are  read  only.  Fields  marked  with  a 
double  asterisk  (**)  are  read  only  while  mapped  in. 


mem_lock  is  true  if  a  segment  is  locked  into  memory  (may  not  be 

swapped  out).  The  privilege  privLockSeg  is  required  to  lock 
a  segment  into  memory. 


mem_advise  is  true  if  the  segment  is  liable  to  be  locked  down  in 

memory.  I/O  segments  should  be  given  this  attribute  by  usut 
programs . 

swap_lock  is  true  if  the  segment  is  locked  into  swap  space  (sticky ; 

must  not  be  deleted).  The  privilege  privStickySeg  is 
required  to  lock  a  segment  into  swap  space. 


sharable  is  true  if  the  segment  may  be  shared  with  other  processes- 
A  segment's  discretionary  access  controls  whether  it  is 
sharable.  A  sharable  segment  can  not  have  its  global  attri¬ 
butes  changed.  For  example,  once  a  segment  is  shared,  it 
can  not  be  made  unsharable.  However,  it  can  still  be  mapped 
anywhere  in  a  process's  address  space. 


growth  indicates  the  growth  direction  of  the  segment.  A  downward¬ 

growing  segment  starts  at  a  high  memory  address  and  ends  at 
a  low  memory  address.  Its  virtual  address  must  be  the  high 
byte  address  (  i.e.  the  address  is  odd).  An  upward  growing 
segment  starts  at  a  low  memory  address  and  ends  at  high 
memory  address.  Its  virtual  address  must  be  the  low  byte 
address(  i.e.  the  address  is  even). 
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*stat_size  is  Che  length  of  the  seguent  in  bytes*  This  must  be  a  mul¬ 
tiple  of  512. 

*stat_seid  is  the  segment's  seid. 

*stat_des  is  the  segment's  open  descriptor  (process-local  segment 
number) . 

*stat_mapped  is  true  if  the  segment  is  currently  mapped  into  the 
process's  address  space. 

**stat_acc  is  the  access  allowed  the  calling  process  to  a  segment.  The 
access  allowed  must  always  be  a  subset  of  the  access  allowed 
this  process  by  the  Til  of  the  segment. 

**stat_loc  is  the  last  known  virtual  location  (in  the  process's  address 
space)  of  a  segment.  If  the  segment  is  upward-growing,  this 
address  must  be  a  multiple  of  64;  if  downward-growing,  this 
address  must  be  one  less  than  a  multiple  of  64. 


SEE  ALSO 

K_build_segment  (II),  K  get  segment  status  (II),  K_set_segment_status 
(II),  priv_struct  (I),  tii_struct  (I) 
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NAME 

tii_struct  -  type  independent  information 
SYNOPSIS 

priv_struct  ■  bits32; 

compart_8et  «  bits  32; 

access_level_type  “  RECORD 
security_category 
integrity_category 
security_compart 
END; 

tii_8truct  “  RECORD 

access_level 
owner 
group 
da 

tii_priv 

END; 

DESCRIPTION 

access_level  contains  the  security  and  integrity  levels,  and  the  secu¬ 
rity  compartment  of  the  object. 

owner  contains  the  (effective)  user  identifier  for  the  object, 

group  contains  the  (effective)  group  identifier  for  the  object, 

da  contains  the  discretionary  access  bits  for  the  object. 

tii_priv  contains  the  privileges  belonging  to  the  object- 

SEE  ALSO 

K _get_object_level  (II),  K_set_object_level  (II),  priv_struct  (I), 
compart_set  (I),  discr_access  (I) 


:  access_level_type ; 
:  cardinal; 

:  cardinal; 

:  discr_access ; 

:  priv_struct 


:  security_cat_type ; 

:  integrity_cat_type; 
:  compart_set 
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NAME 

virt_loc  -  virtual  location 

SYNOPSIS 

domain_type  «  ( 


); 

mem_type  »  (  (*  memory  space  divisions  *) 

null_space , 
d_space , 
i_space 

); 

virt_loc  “  RECORD  (*  virtual  location  *) 

domain  :  domain_type; 
space  :  mem_type; 
address  :  cardinal; 

END; 

DESCRIPTION 

A  virtual  location  specifies  the  domain,  space,  and  address  of  where  the 

location  exists  in  the  user  process. 

domain  contains  either  the  user  domain  or  the  supervisor  domain. 

The  null  domain  is  a  distinguished  value  which  the  kernel 
translates  to  the  domain  from  which  a  kernel  call  has  been 
made* 

space  contains  which  space  within  the  domain  the  data  buffer  is 

located.  The  null  space  is  a  distinguished  value  which  is 
converted  to  data  space  on  separate  I/D  space  programs,  and 
otherwise  to  instruction  space. 

address  contains  the  address  of  the  location  involved. 

SEE  ALSO 

K_remap  (II),  K_rendezvous_segment  (II) 


(*  domains  *) 
null_domain , 
kerne l_domain , 
supervisor_domain , 
user  domain 
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NAME 

C-Karnel_lnterface  -  C  Interface  to  the  Kernel  Calls 
DESCRIPTION 

The  C-Kernel  Interface  consists  of  38  C  routines.  One  interface  routine 
exists  per  Kernel  call.  The  Interface  routines  are  used  in  conjunction 
with  the  types  defined  in  KERcalls-h 

The  general  procedure  followed  in  the  Interface  routines  is  to  put  the 
arguments  of  the  interface  routine  into  one  contiguous  block  of  memory. 
Then  through  an  assembly  language  subroutine,  a  pointer  to  the  block  with 
the  arguments  is  passed  to  the  appropriate  kernel  call.  Upon  completion, 
the  kernel  call  places  any  return  values  into  the  argument  block  and 
returns  an  exception.  This  exception  is  then  passed  upward  by  the  assem¬ 
bly  language  subroutine.  The  interface  routine  unpacks  the  return  values 
from  the  argument  block  and  returns  the  exception  to  the  calling  C  pro¬ 
gram. 

The  38  C  interface  routines  are  contained  in  38  seperate  files,  named 
KOO-c  through  K37.C.  The  assembly  language  subroutines  are  contained  on 
files  named  EMTOO.s  through  EMT37.S*  The  C  routines  are  archived  into 
one  file  (EKL.a)  and  the  assembly  subroutines  into  another  (EMT.a). 

To  use  the  C-Kernel  interface  routines  put  the  archive  file  names  on  your 
compile  command  line.  An  example  of  compiling  a  program,  "test",  that 
uses  the  interface  routines  is: 

CC  test  EKL.a  EMT.a 


PILES 

KOO-c  -  K37.C,  EMTOO.s  -  EMT37.S ,  EKL.a,  EMT.a 

SEE  ALSO 

KERcalls . h 
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NAME 

K_boot 

MODULA  SYNOPSIS 

CONST  b  seg :  seg  deg ; 
VAR  stat:  K  err  num: 

•  •  • 

stat  :■  NK  bwt  (b  gag) : 


C  SYNOPSIS 

sea  das  b  seg; 
lnt  stat: 

•  •  « 

stat  -  K  boot(b  seg) : 

DESCRIPTION 

—  releases  (as  with  K_release_segment)  the  segment  Indicated  by  the 

argument  and  maps  In  (as  with  K_remap)  all  ether  segments  attached  to  the 
process.  Execution  of  the  process  continues  at  location  0  of  the 
process's  supervisor  I-space. 

SEE  ALSO 

K_release_segment (II ) ,  K_remap (II ) 
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NAME 

R_build_segment 

MODtfLA  SYNOPSIS 

CONST  status:  seg  stat  block- 


CONST  da:  dlscr  access; 
VAR  segSeld :  seid : 


VAR 

segDes : 

aeg_ 

des 

VAR 

stat:  K 

err 

Hum 

stat  :■  NK  build  segment (status «  da,  segSeld,  segDes) ; 


C  SYNOPSIS 

seg  stat  black  status : 
dlscr  access  da; 
seld  segSeld; 
seg  des  segDes ; 
lnt  stat : 

•  •  • 

stat  “  K  build  segment  (Astatus .  da,  AsegSeid,  AsegDes) ; 


DESCRIPTION 

K  build  segment  Creates  a  new  process  segment  and  maps  It  Into  the 
process's  virtual  address  space*  Its  operation  Includes  the  following 
actions: 

*  A  global  segment  descriptor  Is  allocated  and  swap  space  is  allocated. 

*  A  proce9S-lecal  segment  descriptor  Is  allocated  and  associated  with 
the  created  segment. 

*  Page  registers  for  the  process  are  chosen  according  to  the  address 
range  specified  for  the  segment,  and  are  partially  Initialized. 

*  Physical  memory  Is  allocated  for  the  segment  and  the  physical  memory 
address  of  the  segment  is  set  up  in  Its  page  registers.  The 
segment's  memory  is  guaranteed  to  be  all  zeros. 


the 


parameters, 
privilege 
particularly  by 
the  privilege 


Information  needed  to  build  the  segment  is  taken  from  the 
From  status  (see  seg  stat  block(I))  are  taken: 

memJLock  whether  to  lock  the  segment  in  memory; 

privLockSeg  is  required  for  this  action 
mem_advise  whether  the  segment  may  be  locked  in  memory, 

I/O  operations 

swap_lock  whether  to  lock  the  segment  in  swap  space: 

privStlckySeg  Is  required  for  this  action 
sharable  whether  to  allow  sharing  of  the  segment  with  other  processes 
growth  segment's  direction  of  growth 
stat_size  size  of  the  segment  in  bytes 

stat_acc  access  the  Calling  process  Is  to  have  to  the  segment 
stat_loc  virtual  location  pf  the  segment  in  the  process's  address 
space 


The  da.  parameter  supplies  the  discretionary  access  for  the  segment,  to  be 
placed  in  its  type-independent  information  (see  tii_struct(I ))  •  The  ac- 


1  - 


-  • 
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cess  t©  the  segment  allowed  by  the  stat  acc  field  of  the  status  parameter 
must  be  a  subset  of  the  access  allowed  by  the  owner  part  of  the  da  param¬ 
eter.  Write-only  access  (write  without  read)  may  not  be  specified  In  ei¬ 
ther  the  stat  acc  field  or  the  da  parameter.  The  remaining  fields  of  the 
type-independent  Information  for  the  segment  are  taken  from  those  of  the 
calling  process. 

Values  produced  by  the  call  are  returned  In  segSeld  (the  SEID  created  for 
the  segment);  and  segDes  (the  process-local  segment  number). 

Segments  may  be  shared  between  processes  providing  that  the  security.  In¬ 
tegrity  and  discretionary  access  checks  would  allow  such  sharing.  Shar¬ 
ing  of  segments  requires  that  the  first  process  to  desire  to  share  the 
segment  create  It.  Subsequent  to  creation,  the  segment  SEID  must  be  made 
available  to  processes  wishing  to  share  the  segment,  typically  either  via 
placing  it  in  a  mutually  agreed  upon  file,  or  by  passing  it  via  an  IPC 
message.  The  other  processes  would  then  issue  K  rendezvous  segment  Calls 
(below)  to  gain  access  to  the  segment. 

It  is  the  responsibility  of  the  processes  sharing  the  segment  to  see  to 
it  that  it  is  properly  initialized,  either  by  the  Kernel's  guarantee  of 
all  zeros,  or  by  explicit  initialization.  The  initialization  may  require 
cooperation  or  mutual  exclusion  to  be  completed  successfully.  This  is 
particularly  true  in  the  case  of  shared  pure  text  segments  which  are  to 
be  resident  in  the  Instruction  Space  on  the  PDP-11 /70.  Since  such  seg¬ 
ments  Cannot  be  written  into,  they  must  be  created  as  writable  segments, 
initialized  from  the  appropriate  image  file,  and  then  have  their  status 
changed  to  make  them  reside  in  the  Correct  space  and  be  non-writable - 
Care  should  be  taken  in  the  design  of  programs  like  the  Process 
Bootstrapper  which  perform  such  initializations  to  assure  that  duplicate 
initialization  attempts  or  multiple  copies  of  the  same  shared  text  seg¬ 
ment  do  not  occur. 

The  virtual  address  and  domain  parameters  shall  be  for  the  calling  pro¬ 
cess  only.  Other  processes  sharing  the  segment  may  map  it  into  their 
virtual  address  spaces  as  desired  through  their  use  of  the 
K  rendezvous  segment  Calls.  Of  course,  some  segments,  e.g.  text  seg¬ 
ments,  may  operate  correctly  only  if  mapped  starting  at  a  specific  virtu¬ 
al  address. 

EXCEPTIONS 

XbSgRng  Bad  segment  range;  set  of  addresses  specified  for  the  segment 

would  lie  outside  a  64K  address  space. 

XbSgSz  Bad  segment  size:  segment  size  of  zero  specified 

XnPgSg  No  page  in  segment:  segment  address  range  does  not  cross  or  is 

not  adjacent  to  some  multiple  of  8K  (address  range  must  include 
an  8K  multiple  or  have  top  address  that  one  less  than  an  8K 
multiple) . 

XnPvLkSg  No  privilege  to  lock  segment;  ,  mem_lock  specified,  but  without 

necessary  privilege 

XnPvStkSg  No  privilege  to  make  sticky  segment:  swap_lock  specified,  but 

without  necessary  privilege 
Cannot  do;  global  resource  exhaustion 


XncnDo 
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XpostEh  Process  open  segment  table  exhaustion:  toe  many  process  seg¬ 

ments 

XvrtMmCfl  Virtual  memory  conflict:  some  subset  of  the  address  range  of 

this  segment  would  use  a  page  register (s)  already  in  use  by  an 
existing  segment  (high-order  three  bits  the  same). 

Write-only  segment:  attempt  to  create  write-only  segment 


XwOnlSg 
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NAME 

K  close  -  close  a  file 


MODULA  SYNOPSIS 

CONST  od:  openDescrlptor ; 
VAR  status:  K  err  num; 

status  NK  close (od) ; 


C  SYNOPSIS 

char  od; 
int  status ; 

status  -  R  close(od) ; 


DESCRIPTION 

R  close  closes  the  file,  terminal,  extent,  or  device  Identified  by  the 
given  open  descriptor  (previously  returned  from  a  Recreate  or  a  R_open) . 
Upon  process  exit,  Close  of  all  open  files,  extents,  terminals,  and  dev¬ 
ices  Is  performed  automatically. 

R  close  does  not  cause  any  device  action,  such  as  tape  rewinding. 


SEE  ALSO 

R_Create(II) ,  R_open(II) 
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NAME 

K  create 


MODITLA  SYNOPSIS 

CONST  protoSeld :  geld ; 

CONST  om:  /penModes : 

CONST  da:  dlscr  access : 

CONST  stCap :  openDescrlptor : 

VAR  fSeid:  geld; 

VAR  od:  openDescrlptor ; 

VAR  atat:  K  err  turn; 

atat  :■  NK  create(protoSeld .  em.  da.  stCap ,  f Seld.  od) ; 


C  SYNOPSIS 

seld  protoSeld; 
open  mode  om; 
dlacr  access  da; 
openDescrlptor  atCap ; 
aeld  f Seld ; 
openDeacrlptor  od; 

Int  atat ; 

•  o  • 

atat  -  K  create  (protoSeld.  om.  da.  8tCap.  AfSeld,  &od) ; 

DESCRIPTION 

K  create  creates  and  opens  a  new  file  on  the  Same  file  system  as  the  file 
protoSeld.  protoSeld  need  not  refer  to  an  actual  file;  only  the  name 
space  partition  part  of  the  seld  is  examined  to  determine  which  file  sys¬ 
tem  is  to  be  used. 

The  file  la  created  with  size  zero,  the  subtype  specified  by  atCap.  and 
Is  opened  with  the  specified  open  modes,  which  must  be  valid  open  modes 
as  defined  for  K  open(II) .  The  file  is  created  with  a  link  count  of 
zero.  This  Implies  that  the  file  will  be  deleted  when  closed  by  the 
creating  process  unless  the  link  count  of  the  file  Is  first  incremented 
by  K  link (II).  Use  of  K  llnk(II)  is  normally  restricted  to  the  UNIX 
directory  manager,  which  thus  restricts  the  creation  of  permanent  files 
to  those  under  the  control  of  the  directory  manager. 

The  seld  of  the  new  file,  fSeid.  Is  chosen  pseudo-randomly  by  the  system. 
The  concept  of  re-creating  an  existing  file  is  thus  not  meaningful. 

The  open  descriptor  od  Is  a  local  name  which  the  process  can  subsequently 
use  to  access  the  created  file. 

SEE  ALSO 

K_open(II),  K_close (II ) 
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«.  NAME 

K_device_£unctien  -  perform  arbitrary  I/O  function 
MODULA  SYNOPSIS 

|  “*  CONST  od:  openDescriptor ; 

CONST  funct :  ioFunction: 

CONST  blockNo:  f BlockNumber ; 

-  CONST  inP:  p  block: 

i  CONST  outP :  p  block; 

1  CONST  id:  asyncld : 

VAR  errs:  ioStatus  : 

!  ""  VAR  bytesDone:  cardinal; 

VAR  status:  K  err  num: 

status  '»  NK  device  functioned.  funct .  blockNo,  inP,  outP,  id,  errs ,  bytesPone) ; 


i 

,s 


I 


C  SYNOPSIS 

openDe  ,criptor  od; 
lnt  funct ; 
long  blockNo; 
pblock  inp ; 
pblock  outp ; 
lnt  id; 

IoStatus  errs : 
lnt  bytes ; 
int  status ; 

0  o  o 

status  "  K  device  functioned,  funct ,  blockNo.  &inp.  &outp,  id,  &errs ,  &bytes) ; 


PESCRIPTION 


K  device  function  can  be  used  for  performing  all  I/O  functions*  There 
are  a  number  of  I/O  functions,  some  of  which  have  meaning  only  for  cer¬ 
tain  devices.  The  parameter  blocks  InP  and  outP  define  the  memory  areas 
to  be  used  for  input  (into  memory)  and  output  (from  memory).  Either  or 
both  parameter  blocks  may  be  null  (size  ■  0)  depending  on  the  require¬ 
ments  of  the  I/O  function. 

SPECIFIC  FUNCTIONS 

Functions  are  specified  in  the  funct  argument. 


REAP 

WRITE 

SETEOMCHARS 

REWIND 

UNLOAD 


Read,  (same  as  K  read  block(II))  Valid  inP  and  open 
for  read  required. 

Write,  (same  as  K  write  block(II))  Valid  outP  and 
open  for  write  required. 

Sets  the  set  of  characters  considered  to  end  a  single 
input  request  for  a  terminal.  See  KSOS  Input/Output 
Guide. 

Rewind  (tape  only).  Open  for  write  required. 

Unload  removable  medium.  Rewinds  tapes  i  off-line 
condition,  steps  disk  drives  where  hardware  permits. 
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WRITEMARK 

SETDENSITY 

SETTERMMODES 1 

SETTERMMODES  2 


GETTERMMODES 

SETFILESIZE 


ERASEFILE 

VOLUMEVALID 

VOLUMEINVALID 

INPUTWAIT 


SETPATH 


Open  for  write  required- 

Write  tape  mark-  Open  for  write  required. 

Set  tape  writing  density-  Open  for  write  required. 
The  density  (800  or  1600)  is  placed  in  the  blockNo 
argument  - 

Set  raw  mode,  echo,  etc-  for  terminals  -  9ee  KSOS 
Input /Output  Guide.  Open  for  read  and  write 
required. 

Set  parity,  density,  etc-  See  KSOS  Input /Output 
Guide.  Open  for  read  and  write  required,  and  the 
Caller  must  have  the  privilege  to  set  these 
security-related  modes.  Open  for  read  and  write 
required.  [requires  prlvSetCemm] 

Get  terminal  modes  -  see  KSOS  Input/Output  Guide. 

Open  for  read  and  valid  inP  required. 

Set  byte  size  of  file-  The  size  is  submitted  in 
blockNo,  and  must  be  compatible  with  the  Current  high 
written  block  of  the  file.  (bytes  +  511)  DIV 

512  -  blocks)  This  function  does  not  allocate  or 
release  file  space.  Open  for  write  required'. 

Get  rid  of  all  space  in  a  file.  Open  for  write 
required. 

Mark  removable  medium  as  usable.  Open  for  read  and 
write  required.  [Requires  prlvlmmlgrate] 

Mark  removable  medium  as  unusable-  Where  hardware 
permits,  performs  an  ONLOAD.  Open  for  read  and  write 
required- 

This  function  is  used  to  wait  until  input  is  avail¬ 
able  from  a  terminal.  It  is  only  valid  as  an  asyn¬ 
chronous  request,  and  only  for  a  terminal.  When  an 
INPUTWAIT  request  completes,  a  following  K  read  block 
request  for  input  from  the  terminal  will  return 
immediately  with  input  data.  Thus,  the  effect  of 
asynchronous  terminal  reads  (which  are  not  supported) 
is  available  by  performing  an  INPUTWAIT  to  wait  until 
input  is  available,  and  then  when  the  asynchronous 
completion  message  is  received,  performing  a 
K  read  block  request-  Open  for  read  is  required. 
Connect  physical  terminal  to  a  different  logical  ter¬ 
minal  path.  The  desired  path  number  is  placed  in  the 
blockNo  argument.  Open  for  read  and  write  required. 
[Requires  prlvSetPath] 


ASYNCHRONOUS  REQUESTS 

I/O  and  computation  (and  to  a  limited  extent  I/O  and  I/O)  may  be  over¬ 
lapped  within  a  single  process.  Normal  calls  to  K  device  function. 

K  read  block  ,  and  K  write  block  should  have  a  zero  in  the  id  argument* 
Such  requests  wait  until  the  I/O  operation  is  complete.  If  anything  else 
is  placed  in  the  id  argument,  the  request  is  asynchronous  and  the  call 
may  return  before  the  operation  is  complete.  When  the  operation  com¬ 
pletes,  an  I/O  completion  message  (see  the  loCompletionMessagetype  )  will 
be  sent  to  the  process  which  did  the  K  device  function  (or  K  read  block 
or  K_write_block)  Call. 
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Only  when  status  Is  XOK  and  errs.devlndep  is  Xasvnc  should  an  I/O  comple¬ 
tion  message  be  expected*  On  asynchronous  requests,  some  errors  are 
reported  through  errs.devlndep  in  the  call  and  some  are  reported  through 
the  errs.devlndep  field  in  the  I/O  completion  message.  It  is  generally 
possible  to  have  several  requests  in  progress  for  different  devices  from 
the  same  process,  but  an  asynchronous  request  for  a  busy  device  will  be 
delayed  until  the  device  is  available. 

SEE  ALSO 

K_read_block(II) ,  K_write_block(II) 
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NAME 

K_f©rk 

MODOLA  SYNOPSIS 

VAR  own :  geld ; 

VAR  other:  geld; 

VAR  stat :  K  err  num; 

•  •  o 

stat  ; ■  NK  fork (own,  other); 


C  SYNOPSIS 

seld  own; 
seid  other : 
lnt  stat ; 

•  •  • 

stat  -  K  fork  ( Sown,  Aether) ; 

DESCRIPTION 

The  K  fork  primitive  creates  a  process.  The  new  process  is  remembered  as 
a  child  of  the  Caller  (parent) .  The  child  is  an  exact  duplicate  of  the 
parent.  The  process  id  of  the  parent  is  returned  to  the  child.  The  pro¬ 
cess  id  of  the  child  is  returned  to  the  parent.  The  program  counter  of 
the  parent  is  not  adjusted  as  it  is  in  standard  UNIX.  The  returned  pro¬ 
cess  id  will  be  sufficient  to  distinguish  parent  and  child.  The  type  in¬ 
dependent  information  of  the  child  process  is  identical  to  the  type  in¬ 
dependent  Information  of  the  parent  process. 

The  non-sharable  segments  of  thi  process  are  Copied  into  new  segment  in¬ 
stances  for  the  child.  The  reference  counts  of  sharable  segments  are  in¬ 
cremented.  The  process  local  segment  names  are  the  same  in  both  the 
parent  and  child,  although  in  the  Case  of  non-sharable  segments  they 
refer  to  a  different  segment  instance  (and  therefore,  a  different  segment 
SEID)  for  the  child  than  for  the  parent. 

The  child  inherits  the  open  objects  of  the  parent.  That  is,  each  object 
that  is  open  in  the  parent  is  opened  in  the  child,  and  has  the  same  local 
open  object  descriptor.  The  ©pen  counts  of  the  open  objects  so  inherited 
are  Incremented  to  reflect  the  fact  that  another  process  (the  child)  has 
them  open.  If  the  parent  has  an  object  open  for  exclusive  use,  the 
K  fork  Call  fails,  preventing  two  processes  from  having  simultaneous  ac¬ 
cess  to  the  same  exclusive  use  object. 

An  error  is  returned  in  stat  if  the  pool  of  available  processes  has  been 
exhausted. 
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NAME 

fC_get_file_status 


MODULA  SYNOPSIS 

CONST  fSeid:  geld: 

CONST  stCap :  openDescriptor ; 

VAR  status:  file  stat  block: 

VAR  stat:  K  err  nua; 

stat  :■  NK  get  file  status (fSeid,  stCap .  status) : 


C  SYNOPSIS 

aeld  f Seid ; 
openDescriptor  stCap ; 
file  stat  black  status ; 

Int  stat ; 

•  •  • 

stat  “  K  get  file  status  (f Seld,  stCap .  Astatus) ; 

DESCRIPTION 

K  get  file  status  returns  the  type  dependent  Information  associated  with 
a  file,  terminal,  extent,  or  device.  This  Information  Includes  the  size 
of  the  object  In  bytes  (zero  for  non-addressable  devices),  and  the  time 
of  the  last  open  for  writing  (meaningful  for  files  only) .  The  Invoking 
process  must  have  read  access  to  the  file  with  respect  to  the  mandatory 
security  and  integrity  rules  only.  No  discretionary  access  checking  Is 
performed. 


The  stCap  arguement  to  this  Call  is  ignored 
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NAME 

K  get  obj ect_level 


MODULA  SYNOPSIS 

CONST  obISeld:  geld; 

VAR  level:  til  struct; 

VAR  atat:  K  err  num; 

atat  : ~  NK  get  object  leveKobjSeld.  level) ; 


C  SYNOPSIS 

geld  ebjSeld; 
til  atruct  level: 
lnt  atat ; 

atat  “  K  get  object  level  (ebjSeld.  Alevel) ; 

DESCRIPTION 

Given  ebjSeld,  the  primitive  K  get  object  level  return8  the  type  Indepen¬ 
dent  lnfermatien  for  an  object  In  level. 
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NAME 

K  get  process  status 


MODULA  SYNOPSIS 

CONST  procSeld:  seld; 

VAR  status :  proc  stat  block: 

VAR  stat:  K  err  num; 

stat  : “  NK  get  process  status(procSeid.  status) ; 


C  SYNOPSIS 

seld  procSeld; ; 

proc  stat  block  status : 

int  stat : 

stat  -  K  get  process  status  (procSeld.  Astatus) ; 

DESCRIPTION 

The  K  get  process  status  call  returns,  in  the  status  parameter,  the  type 
dependent  information  about  the  process  specified  by  procSeid.  A  process 
may  successfully  request  information  of  processes  that  it  can  access 
given  its  level  and  the  level  of  the  target  process. 
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NAME 

K  get  segment  status 

MODULA  SYNOPSIS 

CONST  segSeid:  seid: 

CONST  segDES :  seg  des; 

VAR  status:  seg  stat  block; 
VAR  stat:  X  err  nua: 


C  SYNOPSIS 

seld  segSeid : 
seg  des  segDes ; 
seg  stat  block  status ; 
int  stat ; 


get  segment  status  (segSeid,  Astatus) : 


DESCRIPTION 

K  get  segment  status  returns,  in  the  parameter  status,  the  type  dependent 
information  associated  with  a  segment  segSeid.  A  process  may  successful¬ 
ly  obtain  type  dependent  status  about  any  segment  from  which  information 
could  flow  to  the  process.  No  discretionary  access  checking  shall  be 
performed. 


EXCEPTIONS 


XbSgDes  Bad  segment  designator:  This  segment  designator  is 

inactive. 


XbSgSd  Bad  segment  seid:  segSeid  is  not  the  seid  of  an  exist¬ 

ing  segment  or  process  does  not  have  manditory  (securi¬ 
ty)  access  to  the  segment. 

XnSgDes  Not  a  segment  designator:  This  number  is  outside  the 

set  of  segment  designators. 
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NAME 

K  halt 

MODULA  SYNOPSIS 

VAR  atat :  K  err  num; 

atat  NK  halt; 


C  SYNOPSIS 

tnt  atat : 

atat  •  K  halt  (  ) ; 

DESCRIPTION 

K  halt  causes  the  entire  system  te  halt.  Use  of  this  call  is  restricted 
to  processes  with  the  privHalt  privilege. 

SEE  ALSO 

priv_struct(I) 


i 
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NAME 

K_interrupt_return 

MODULA  SYNOPSIS 

VAR  stat;  K  err  num; 

atat  NK  interrupt  return: 


C  SYNOPSIS 

lnt  atat : 

atat  ■  K  interrupt  return  (  ) ; 

DESCRIPTION 

K  interrupt  return  provides  an  atomic  return  operation  from  pseudo  inter¬ 
rupts.  It  Can  be  thought  of  as  being  analogous  to  the  PDP-11  RTI  and  RTT 
Instructions.  When  a  pseudo  interrupt  occurs,  the  program  counter,  pro¬ 
cessor  status  word,  and  current  pseudo  interrupt  level  are  saved  in  a 
pseudo  interrupt  vector  for  the  particular  type  of  pseudo  Interrupt  which 
occurred.  In  the  PDP-11  Implementation,  these  vectors  are  located  at 
fixed  locations  in  the  supervisor  domain.  The  K  interrupt  return  call 
restores  the  process,  state  from  these  saved  values*  Because  the  inter¬ 
rupted  process  state  is  accessible  to  the  process,  the  K  interrupt  return 
Call  checks  the  saved  state  prior  to  restoring  it.  The  process  is  not  be 
permitted  to  increase  its  privileges  or  accessible  domains.  (Similar 
checking  takes  place  in  the  processing  of  the  pseudo  interrupt  Itself.) 
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NAME 

K_invoke 

MODULA  SYNOPSIS 

CONST  lmmSeld:  geld : 

CONST  arg:  seg  des : 

VAR  stat :  K  err  nun: 

stat  :*  NR  invoke (immSe id.  arg) ; 


C  SYNOPSIS 

aeld  ImmSeid ; 
seg  des  arg; 
int  stat; 

•  •  • 

stat  -  K  invoke  (lmmSeld,  arg) ; 

DESCRIPTION 

The  purpose  of  the  K  Invoke  primitive  Is  the  Invocation  of  potentially 
privileged  software.  The  effect  of  this  call  Is  to  replace  the  existing 
segment  map  (including  the  executing  text  segment)  by  a  new  process  im¬ 
age.  All  segments  will  be  released  except  for  the  argument  segment 
specified  by  arg.  The  new  process  image  has  only  the  intermediary  seg¬ 
ment  and  the  argument  segment  active  (mapped  in).  Arguments  for  use  by 
the  intermediary  process  may  be  placed  in  the  argument  segment.  The  ex¬ 
act  format  of  the  argument  segment  is  determined  by  the  particular  in¬ 
termediary  specified  in  the  Call.  The  argument  segment  may  be  used  by 
the  intermediary  as  a  scratch  pad  as  the  intermediary  builds  any  other 
segments  it  requires.  It  is  the  responsibility  of  the  newly  executing 
program  (the  intermediary)  to  create  its  own  working  segments.  The 
privileges  of  the  process  are  set  to  those  associated  with  the  intermedi¬ 
ary  segment.  In  the  PDP-11 /70  implementation,  the  intermediary  is  mapped 
into  location  0  of  the  supervisor  domain  instruction  space,  and  the  argu¬ 
ment  segment  is  mapped  out.  The  intermediary  may  perform'  any  arbitrary 
function.  Thus,  applications  of  the  KSOS  Kernel  may  elect  to  create  spe¬ 
cialized  intermediaries  to  perform  specific  functions.  The  only  pre¬ 
defined  intermediary  is  the  Process  Bootstrapper ,  described  next. 

The  Process  Bootstrapper  segments  implement  a  trusted  process  whose  sole 
purpose  is  the  creation  of  other,  potentially  trusted,  environments  by 
replacing  itself  with  image  from  the  prototype  file  whose  name  is  passed 
in  as  an  argument.  The  Process  Bootstrapper  has  the  following 
privileges : 


to  set  privileges 

to  set  the  effective  owner 


to  set  the  security  and  integrity  level 
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to  realize  execute  permissions  (i.e.  use  the  execute  permissions  for  read 
access  attempts) 

Using  the  parameters  specified  in  the  argument  segment,  the  Process 
Bootstrapper  builds  a  new  set  of  process  segments  conforming  to  the  pro¬ 
cess  prototype  file.  The  privileges  for  the  new  environment  is  obtained 
from  the  process  prototype  file.  If  the  prototype  file  has  no  privileges 
associated  with  it,  the  new  environment  is  unprivileged.  If  the  proto¬ 
type  file  specifies  that  it  is  to  execute  in  a  different  discretionary 
access  domain,  the  bootstrap  changes  the  effective  user  and/or  group  of 
the  process  to  the  owner  of  the  prototype  file.  The  new  trusted  process 
is  then  set  into  execution  by  the  Process  Bootstrapper.  Note  that  a  com¬ 
pletely  trusted  path  exists  from  the  K  invoke  call,  through  process  con¬ 
struction,  to  the  execution  of  the  trusted  software. 

The  use  of  the  K  invoke  Call  is  not  limited  to  the  invocation  of  trusted 
processes.  Untrusted  processes  may  also  be  executed  through  the  K  invoke 
call.  If  change  of  discretionary  access  domain  or  privilege  is  net  re¬ 
quired  by  the  type  dependent  information  associated  with  the  process  pro¬ 
totype  file,  the  process  bootstrap  simply  removes  all  privileges  prior  to 
setting  the  new  image  into  execution. 

The  privilege  information  associated  with  a  process  prototype  file  is 
controlled  by  the  Privilege  Control  Process,  a  restricted  use  program 
discussed  in  the  Non-Kernel  Security-Related  Software  CPCI  Specification 
[NKSR  78J. 


SEE  ALSO 

PBB(III),  K_spawn(II) 
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NAME 

K_link 

MOD0LA  SYNOPSIS 

CONST  fSeid:  geld; 

VAR  stat:  K  err  nun; 

•  •  • 

stat  NK  link(fSeid); 


C  SYNOPSIS 

seid  fSeid: 
int  stat ; 

stat  “  K  link  (fSeid) ; 

DESCRIPTION 

K  link  Increments  the  reference  ceunt  of  a  Kernel  file  specified  by  the 
seid  fSeid*  The  reference  count  is  normally  used  to  indicate  the  number 
of  UNIX  directory  entries  which  point  to  this  SEID.  Applications  of  the 
KSOS  Kernel  which  do  not  use  the  UNIX  directory  structure  and  semantics 
may  use  the  reference  count  for  other  purposes.  The  reference  count  may 
only  be  incremented  by  processes  with  the  prlvLink  privilege.  Such 
processes  should  be  Carefully  designed  to  reduce  the  bandwidth  of  the 
resultant  confinement  channels  and  to  preserve  the  integrity  of  the 
higher  level  directory  structure,  if  any.  The  security  and  integrity 
checking  on  K  link  is  as  if  the  user  were  reading  and  writing  the  file. 
No  discretionary  access  checking  is  performed.  Thus,  the  processes 
privileged  to  use  K  link  may  implement  whatever  discretionary  checking 
they  choose. 

SEE  ALSO 

K  create (II).  K  unlink(II). 
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NAME 

K_mount 

MODULA  SYNOPSIS 

CONST  extSeld :  seld; 

CONST  readonly :  boolean : 

VAR  nap:  nsp  type; 

VAR  stat:  K  err  nua; 

•  •  • 

stat  NK  mount (extSeld.  readonly,  nsp) ; 


C  SYNOPSIS 

seid  extSeld; 
nsp  type  nsp ; 
boolean  readonly ; 
lnt  stat ; 

•  o  o 

stat  -  K  mount  (extSeld.  readonly.  &nsp) ; 


DESCRIPTION 

The  K  mount  Call  performs  the  function  of  associating  a  particular  file 
name  space  partition  with  the  extent,  extSeld.  making  it  possible  to 
access  files  in  the  mounted  file  system. 

Use  of  this  call  requires  the  privilege  privMount  which  normally  res¬ 
tricts  the  use  of  this  Call  to  the  NKSR  'mount'  program.  It  is  the 
responsibiity  of  the  privileged  program  to  insure  that  the  file  system 
being  mounted  is  a  valid  file  system,  that  the  Immigration  Officer  func¬ 
tion  has  approved  its  use,  and  that  the  user  invoking  'mount'  is  author¬ 
ized  to  operate  on  the  file  system  involved. 

Each  mounted  KSOS  file  system  belongs  to  a  different  name  space  parti¬ 
tion.  The  Kernel  assures  this  by  assigning  a  name  space  partition  to  the 
file  system  when  the  file  system  is  mounted.  The  Immigration  Officer 
software  [NKSR  78]  maintains  a  data  base  of  file  systems  currently  immi¬ 
grated.  When  a  extent  is  mounted,  the  Kernel  shall  update  an  internal 
data  base  which  tells  it  on  which  extent  the  SEIDs  in  the  mounted  name 
space  partition  may  be  found.  The  nsp  value  returned  by  the  K  mount  call 
determines  the  name  space  partition  which  the  Kernel  will  expect  in 
operations  referring  to  files  in  the  newly  mounted  file  system. 

The  first  K  mount  after  startup  of  the  Kernel  will  always  return  the  same 
value,  and  by  convention  this  value  is  associated  with  the  "root"  file 
system. 

It  is  possible  to  mount  a  file  system  as  read  only  by  setting  readonly  to 
true  in  which  case  no  file  on  the  file  system  can  be  opened  for  writing, 
new  files  cannot  be  created,  and  existing  files  cannot  be  altered  or 
deleted.  The  physical  device  may  be  placed  in  write-protect  mode  without 
interfering  with  read-only  mounts. 


1 


K_mount(II) 


KSOS  9/8/80 


K_mount(II) 


Each  file  system  centains  type  Independent  information.  The  security  and 
integrity  levels  of  the  file  system  shall  be  interpreted  as  the  maximum 
levels  allowed  for  any  file  on  the  extent.  The  Kernel  prevents  K  create 
operations  by  any  process  not  permitted  data  flow  to  the  file  system 
under  the  security  model. 

Note  that  extents  may  contain  data  structures  other  than  KSOS  file  sys¬ 
tems*  A  given  extent  may  be  assigned  for  private,  non-file  system  use. 
However,  only  extents  belonging  to  the  subtype  'file  system'  may  be 
mounted . 

SEE  ALSO 

K_create(II) 
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NAME 

K_nap 

MODOLA  SYNOPSIS 

CONST  tlmeOut :  cardinal : 
VAR  scat:  K  err  num; 

stat  :■  NK  nap (tlmeOut) ; 


C  SYNOPSIS 

Cardinal  tlmeOut ; 
lnt  stat; 

stat  “  K  nap  (tlmeOut) ; 

DESCRIPTION 

K  nap  is  a  mechanism  far  explicitly  giving  up  the  processor  when  a  higher 
level  blocking  condition  occurs.  This  situation  occurs  when,  for  exam¬ 
ple,  processes  implementing  semaphores  on  top  of  the  Kernel  become  logi¬ 
cally  blocked  on  a  semaphore.  K  nap  provides  an  alternative  to  busy 
waiting  for  the  semaphore.  The  tlmeOut  argument  is  the  incremental  time 
(in  l/60th  second  clock  ticks)  before  which  the  process  should  not  be 
rescheduled  by  the  Kernel.  Processes  using  K  nap  should  check  that  the 
logical  condition  for  which  they  were  waiting  has  occurred  when  they  are 
activated. 
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NAME 

K_open  -  open  a  file,  terminal,  extent,  or  device 


MODULA  SYNOPSIS 

CONST  fSeid:  seid; 

CONST  om:  OpenModes : 

CONST  atCap :  openDescriptor ; 

VAR  od:  openDescriptor : 
status:  K  err  num; 

status  NK  open(fSeid.  om,  atCap .  od) ; 


C  SYNOPSIS 

aeid  fSeid ; 

KopenModes  om; 
char  atCap ; 
char  od; 
int  status ; 

status  «  K  open(fSeld,  om,  scCap ,  &od) ; 


DESCRIPTION 

K  open  opens  the  file,  terminal,  extent,  or  device  specified  by  fSeid. 
The  open  descriptor  is  returned  in  the  arguement  od. 

No  initialization  of  the  device  occurs  when  a  device  is  opened.  Devices 
which  are  not  ready  (no  tape  mounted,  etc.)  can  be  opened,  but  devices 
which  are  not  physically  present  cannot  be  opened. 

om  contains  the  requested  open  modes,  which  are 

om.reaa  Open  for  reading 

om. write  Open  for  writing 

om. exclusive  read  Lock  out  all  other  readers 

om- exclusive  write  Lock  out  all  other  writers 

Only  the  following  Combinations  of  modes  are  permitted: 

exclusive 


read 

write 

read 

write 

false 

false 

false 

Normal  read- 

false 

true 

false 

false 

Normal  write. 

true 

true 

false 

false 

Normal  read  and  write. 

true 

true 

false 

true 

Lock  out  all  other  writers 

true 

true 

true 

true 

v 

When  an  open  request  falls  because  of  an  exclusive  use  blockage,  an 
exception  is  return  ad.  There  is  no  blocking  or  delay  associated  with 
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exclusive  use  failure-  Note,  though,  that  exclusive  use  is  available 
only  to  those  with  the  ability  to  open  for  writing. 

SUBTYPES 

Subtypes  are  predefined  openable  objects  which  control  access  to  other 
objects.  If  an  object  is  subtyped,  a  requestor  can  open  it  for  writing 
only  if  the  subtype  is  already  open  for  writing  to  that  process  and  the 
open  descriptor  of  the  subtype  is  submitted  in  the  stCap  argument.  A 
similar  rule  applies  for  reading.  Piles  may  be  created  in  a  subtype  by 
providing  the  subtype,  opened  for  reading  and  writing,  to  K  create (II). 
Subtypes  are  primarily  used  by  the  directory  manager  to  protect  direc¬ 
tories  and  are  of  limited  use  to  most  users. 


SEE  ALSO 

K_create(II),  K_close(II) 
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NAME 

K_post 

MODULA  SYNOPSIS 

CONST  receiver :  geld; 

CONST  psint :  boolean : 

CONST  mag :  mag  struct: 

VAR  stat:  K  err  num; 

stat  :•  NK  post(receiver ,  psint.  msg) : 


C  SYNOPSIS 

seid  receiver; 
boolean  psint ; 
msg  struct  msg; 
int  stat : 

«  •  • 

stat  »  K  post  (receiver,  psint .  &msg) ; 

DESCRIPTION 

K  post  sends  a  short  message  to  another  process  specified  by  the  seid  re¬ 
ceiver  .  A  pseudo  interrupt  is  asserted  at  the  destination  process,  if 
selected,  and  if  the  receiving  process  has  IPC  pseudo  interrupts  enabled 
(i.e*  that  its  pseudo-interrupt  level  is  sufficiently  low  to  allow  pseudo 
interrupts).  A  header  is  attached  to  the  message  indicating  the  SEID  of 
the  originating  process. 


The  type  independent  information  for  the  two  processes  is  used  to  deter¬ 
mine  rights  of  the  originating  process  to  communicate  with  the  the  desti¬ 
nation. 
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NAME 

K_read_block  -  perform  read 

MODULA  SYNOPSIS 

CONST  od:  openDescrlptor ; 

CONST  blockNo:  fSlockNumber; 

CONST  inP;  p  block: 

CONST  Id:  asvncld; 

VAR  errs:  ioStatus ; 

VAR  bytesRead:  cardinal : 

VAR  status:  K  err  num; 

status  :•  NK  read  block(od,  blockNo .  inP.  id.  errs .  bytesRead) ; 


C  SYNOPSIS 

openDescriptor  od; 
long  blockNo; 
pblock  inp; 
int  Id; 

IoStatus  errs ; 
int  bytes ; 
int  status ; 

status  -  K  read  block (od.  blockNo.  &inp.  id.  Aerrs .  Abytes) ; 

DESCRIPTION 

K  read  block  is  used  to  request  reading  from  files,  terminals,  extents, 
and  devices.  The  parameter  block  InP  defines  the  memory  area  to  be  used 
for  input. 

Files  and  extents  are  stored  in  units  of  512  byte  blocks.  From  1  to  64 
blocks  Can  be  read  from  a  file  or  extent  with  one  request.  A  single  big 
request  is  much  faster  than  many  small  requests.  Files  which  contain 
"holes"  (unwritten  blocks)  are  treated  on  read  as  if  the  unwritten  block 
contained  all  zero  bytes.  Transfers  are  always  in  multiples  of  512 
bytes,  regardless  of  the  byte  size  of  the  file. 

Terminals  may  be  read  and  written  in  sizes  from  1  to  128 

Devices  may  have  different  rules  for  each  device  on  block  size.  See  the 
specific  device  in  (VT).  KSOS  Input/OutPut  Guide 

ASYNCHRONOUS  REQUESTS 

See  K  device  function(II) .  To  make  a  normal,  synchronous,  request,  the 
id  argument  should  be  zero. 

SEE  ALSO 

K_device_f unction (II) ,  K_write_block(II) 
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EXCEPTIONS 

See  K  device  function(II ) . 


ERROR  CODES 

Error  information  is  returned  in  errs .  After  an  operation  which  did  not 
return  an  exception,  errs .devlndep  contains  one  of  the  values  given 
below,  and,  for  operations  on  devices,  errs.devDep  contains  16  bits  of 
hardware  status  as  described  in  (VI)  under  the  specific  device.  See 
K  device  function (II)  for  further  details. 
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NAME 

K_receive 

MODtILA  SYNOPSIS 

CONST  timeOut:  cardinal: 

CONST  n  oil:  pseudo  int  levels ; 

VAR  mag :  ipc  block: 

VAR  stat:  K  err  num: 

stat  : “  NK  receive (timeOut.  n  pil.  mag) ; 


C  SYNOPSIS 

cardinal  timeOut : 
pseudo  int  levels  n  pil: 
ipc  block  mag; 
int  stat; 

•  o  • 

stat  m  K  receive  (timeOut.  n  pil.  &mag) ; 

DESCRIPTION 

K  receive  suspends  the  execution  of  a  process  until  the  receipt  of  an  IPC 
message  or  until  a  time  out.  The  return  value  indicates  the  condition 
which  caused  the  process  to  be  restarted. 

The  first  message  in  the  queue  of  received  IPC  messages  is  returned.  If 
more  than  timeOut  'dock  ticks'  expire  before  any  IPC  messages  are  re¬ 
ceived,  no  message  is  returned  and  the  error  code  so  Indicates.  The 
n  pil  parameter  sets  the  pseudo  interrupt  level  of  the  process  before  be¬ 
ginning  the  wait.  This  is  analogous  to  a  K  set  pil  Call. 
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NAME 

K_release_process 

MODITLA  SYNOPSIS 

CONST  procSeld:  geld ; 
VAR  stat;  K  err  num: 


stat  : -  NK  release  process (procSeld) ; 


C  SYNOPSIS 

seid  procSeld: 
int  stat : 

stat  “  K  release  process  (procSeld); 

DESCRIPTION 

K  release  process  deallocates  all  of  the  Kernel  level  resources  associat¬ 
ed  with  the  named  process.  A  K  release  process  call  with  the  null_seid 
argument  releases  the  calling  process.  Only  a  process  with  the  same  own¬ 
er  or  a  process  privileged  to  change  its  owner  may  issue  a 
K  release  process  for  another  process.  The  effects  of  K  close  for  all 
open  files  and  of  a  K  release  segment  for  all  the  segments  of  the  process 
occur.  Shared  segments  remain  intact  un.1  as  the  reference  count  to  the 
segment  has  reached  zero.  Segments  with  a  zero  reference  count  are  deal¬ 
located  unless  they  have  been  created  to  be  'sticky'.  Files  are  deallo¬ 
cated  if  their  link  counts  and  open  counts  are  zero.  The  process  seid 
becomes  unknown. 
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NAME 

K_release_segment 

MODtJLA  SYNOPSIS 

CONST  sag:  seg  deg; 

VAR  stat:  K  err  nun: 

stat  NK  release  segment (seg) ; 


C  SYNOPSIS 

seg  des  seg: 
in t  stat ; 

stat  *  K  release  segment  (seg) ; 

DESCRIPTION 

The  primitive  K  release  segment  releases  the  Kernel  level  resources  asso¬ 
ciated  with  the  specified  segment.  The  segment  is  not  deleted  if  other 
processes  are  still  using  it  or  if  its  swap_lock  (sticky)  bit  is  set. 

SEE  ALSO 

seg  stat  block  (I) 

EXCEPTIONS 

XbSgDes  Bad  segment  seid:  segSeid  is  not  the  seid  of  an  exist¬ 

ing  segment  or  process  does  not  have  manditory  (securi¬ 
ty)  access  to  the  segment. 


XnSgDes 


Not  a  segment  designator:  This  number  is  outside  the 
set  of  segment  designators. 
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NAME 

K_remap 

MODULA  SYNOPSIS 

CONST  InSeg :  aeg  des : 

CONST  inLoc:  virt  loc: 

CONST  InAcc:  acc  mode: 

CONST  outSeg:  seg  des; 

CONST  outsize:  seg  size; 

CONST  choice:  selector: 

VAR  stat:  K  err  num: 

stat  NK  remap (InSeg.  InLoc.  InAcc.  outSeg.  outSlze.  choice): 


C  SYNOPSIS 

seg  des  InSeg; 
vlrt  loc  InLoc; 
acc  mode  InAcc ; 
seg  des  outSeg; 
seg  size  outSlze; 
selector  choice ; 
int  stat ; 

•  •  • 

stat  »  K  remap  (InSeg.  inLoc.  InAcc.  outSeg.  outSlze.  choice) ; 

DESCRIPTION 

The  K  remap  primitive  permits  the  process  to  change  its  segment  map.  The 
outgoing  segment  is  no  longer  directly  addressable  by  the  process  through 
machine  Instructions.  The  incoming  segment  becomes  directly  addressable 
by  the  process.  The  outgoing  segment  is  not  released.  However,  the 
memory  management  hardware  of  the  segment  to  be  removed  from  the  current 
mapped  set  may  be  used  to  satisfy  the  hardware  requirements  of  the  incom¬ 
ing  segment.  When  a  process  segment  is  mapped  into  the  current  address¬ 
able  set  of  segments,  it  occuppies  the  virtual  address  vector  defined  by 
the  arguments  to  K_remap.  Either  or  both  of  the  segment  designators  may 
be  null.  If  both  are  null  the  call  has  no  effects.  The  incoming  segment 
must  fit  into  the  virtual  memory  and  memory  management  resources  avail¬ 
able  after  the  outbound  segment  is  unmapped.  If  it  does  not,  or  if  any 
of  the  other  error  conditions  occur,  or  if  both  segment  designators  are 
null,  the  call  has  no  effect  on  the  segment  mapping. 

If  the  alter  virtual  location  flag  (vlFlg)  within  the  choice  parameter  is 
TRUE,  the  Incoming  segment  is  mapped  into  the  location  specified  as  argu¬ 
ments  to  the  call,  and  its  status  information  adjusted  to  reflect  this  as 
a  permanent  change.  Otherwise,  the  segment  is  mapped  into  the  location 
specified  in  its  permanent  status  information. 

If  the  alter  discretionary  access  information  flag  (daFlg)  within  the 
choice  parameter  is  TRUE,  the  modes  in  which  this  process  will  access  the 
segment  are  checked  against  the  permitted  access  modes  for  the  segment, 
and  if  allowed,  will  become  the  access  modes  for  the  segment.  This  may 
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alter  the  settings  of  memory  management  hardware  when  the  segment  is 
mapped  back  in. 

If  the  alter  size  flag  (osFlg)  within  the  parameter  choice  is  TRUE,  the 
size  of  the  outbound  segment  are  set  to  the  value  outsize*  The  expansion 
or  truncation  of  the  segment  is  performed  at  the  end  of  segment  specified 
by  the  growth  attribute  of  the  segment  specified  when  built*  Expanded 
parts  of  segments  are  filled  with  zeros.  The  size  change  can  only  be  ap¬ 
plied  to  segments  that  are  not  sharable. 

EXCEPTIONS 

XbSgRng  Bad  segment  range:  set  of  addresses  specified  for  the 

segment  would  lie  outside  a  64  K  address  space* 

XbSgDes  Bad  segment  designator:  this  segment  designator  is 

inactive. 

XinSgAldMp  Incoming  segment  already  mapped. 

XncnDo  Cannot  do:  global  resource  exhaustion. 

XnoAcc  No  access:  cannot  access  this  object* 

XnPgSg  No  page  in  segment:  segment  address  range  does  not 

cross  or  is  not  adjacent  to  some  multiple  of  8  K  (ad¬ 
dress  range  must  include  an  8K  multiple  or  have  top  ad¬ 
dress  that  one  less  than  an  8K  multiple). 

XoutSgAldUmp  Outgoing  segment  already  unmapped. 

Virtual  memory  conflict:  some  subset  of  the  address 
range  of  this  segment  would  use  a  page  register(s)  al¬ 
ready  in  use  by  an  existing  segment  (high-order  three 
bits  the  same). 
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NAME 

K_rendezvous_segment 

MODOLA  SYNOPSIS 

CONST  aegSeid:  seid; 

CONST  location:  virt  loc: 

CONST  access :  acc  mode; 

VAR  segDes :  seg  des ; 

VAR  stat :  K  err  num: 

atat  :»  NK  rendezvous  segment (segSeld.  location,  access .  segDes); 


C  SYNOPSIS 

seid  segSeid; 
virt  loc  location; 
acc  mode  access ; 
seg  des  segDes ; 
int  stat ; 

•  •  • 

stat  •  K  rendezvous  segment  (segSeid.  location,  access .  SsegDes) ; 


DESCRIPTION 

The  Kernel  call  K  rendezvous  segment  is  the  mechanism  by  which  processes 
are  able  to  share  segments*  If  the  segment  requested  exists  and  is  ac¬ 
cessible,  it  is  mapped  into  the  processes  address  space  as  requested, 
providing  that  the  requested  mapping  information  is  valid.  The  Kernel 
will  check  that  the  segment  may  be  mapped  into  the  process  issuing  the 
K  rendezvous  segment  call.  The  checks  include: 


that  the  segment  seid  is  active 
that  the  segment  may  be  shared 

that  the  security/integrity  level  of  the  process  allows  it  to  access  the 
segment 

that  the  discretionary  access  for  the  segment  allows  it  to  be  accessed  in 
the  requested  way 

that  the  virtual  address  supplied  is  valid 


EXCEPTIONS 

XbSgRng  Bad  segment  range:  set  of  addresses  specified  for  the 

segment  would  lie  outside  a  64  K  address  space. 

XbSgSd  Bad  segment  seid:  segSeid  is  not  the  seid  of  an  exist¬ 

ing  segment  or  process  does  not  have  manditory  (securi¬ 
ty)  access  to  the  segment. 


K_rendezvous_segment (IX ) 


KSOS  9/10/80 


K_rendezvous_segment (II ) 


XdupSg  Duplicate  segment:  some  process-local  segment  designa¬ 

tor  is  already  attached  to  the  segment* 

XncnDo  Cannot  do:  global  resource  exhaustion* 

XnPgSg  No  page  in  segment:  segment  address  range  does  not 

cross  or  is  not  adjacent  to  some  multiple  of  8  K  (ad¬ 
dress  range  must  include  an  8K  multiple  or  have  top  ad¬ 
dress  that  one  less  than  an  8K  multiple) • 

XpostEh  Process  open  segment  table  exhaustion:  too  many  process 

segments • 

XsgNoAcc  Segment  no  access:  discretionary  access  of  the  segment 

does  not  allow  the  requested  access. 

Virtual  memory  conflict:  some  subset  of  the  address 
range  of  this  segment  would  use  a  page  register (s)  al¬ 
ready  in  use  by  an  existing  segment  (high-order  three 
bits  the  same) • 
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NAME 

K_secure_terminal_lock 

MODULA  SYNOPSIS 

CONST  tSeld :  geld; 

VAR  stat:  K  err  num: 

stat  : "  NK  secure  terminal  lock(tSeid) ; 


C  SYNOPSIS 

seld  tSeld; 
lnt  stat; 

•  •  • 

stat  *  K  secure  terminal  lock  (tSeid) ; 


DESCRIPTION 

This  Kernel  call  has  been  deleted. 
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NAME 

K_set_da 

MODULA  SYNOPSIS 

CONST  obISeld:  seid; 

CONST  da:  discr  access; 

VAR  stat:  K  err  num; 

Stat  NK  set  da(ob1Seid.  da) ; 


C  SYNOPSIS 

seid  obISeid: 
discr  acces  da; 
int  stat ; 

stat  “  K  set  da  (obJSeid,  da) ; 

DESCRIPTION 

K  set  da  sets  the  discretionary  access  of  the  object  specified  by  the 
first  argument  to  that  given  in  the  second  argument- 
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NAME 

K_aet_f ile_status 
DESCRIPTION 

This  Kernel  call  has  been  deleted. 
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K_se  t_rea l_i d (II) 


NAME 

K_se  t_real_id 

MODOLA  SYNOPSIS 

VAR  atat :  K  err  nurn: 

atat  :«  NK  set  real  id: 


C  SYNOPSIS 

int  atat ; 

atat  -  K  set  real  idQ  ; 

DESCRIPTION 

K  set  real  id  seta  the  process'  effective  id  to  its  real  id.  The  effec¬ 
tive  id  is  set  by  doing  a  K  set  object  level  call,  while  the  real  id  is 
set  by  doing  a  K  set  process  status  call. 


-  1  - 
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NAME 

K_se  t_ob  J  ec  t_le  vel 

MODULA  SYNOPSIS 

CONST  objSeid:  geld: 

CONST  level:  til  struct: 

VAR  atat :  K  err  num: 

stat  :«■  NK  set  object  leveKobiSeid.  level,  choice) ; 

C  SYNOPSIS 

seld  objSeid; 
tii  struct  level ; 
int  stat : 

atat  ■  K  set  object  level  (objSeid,  Slevel) : 

DESCRIPTION 

The  K  set  object  level  primitive  sets  the  security  relevant  type  indepen¬ 
dent  information  for  an  object. 

Processes  with  the  privilege  to  set  object  level  shall  be  capable  of 
changing 

*  the  user  which  owns  the  object 

*  the  group  which  owns  the  object 

*  the  security  level  (security  Category  and  compartments) 

*  the  integrity  level  (integrity  category  and  (presently  null)  com¬ 
partments.) 
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NAME 

K_set_pil 


MODULA  SYNOPSIS 

CONST  new  pil:  pseudo  lnt  levels; 

VAR  old  pil:  pseudo  int  levels; 

VAR  stat:  K  err  num; 

•  •  • 

stat  NK  set  pil(new  pil,  old  pil): 


C  SYNOPSIS 

pseudo  int  levels  new  pil; 
pseudo  init  levels  old  pil: 
int  stat ; 

•  •  • 

stat  ■  K  set  pil  (new  pil.  &old  pil) ; 

DESCRIPTION 

K  set  pil  sets  the  process'  pseudo  interupt  level  to  the  first  argument 
The  process'  old  pseudo  interupt  level  is  returned  in  the  old_pil  field. 
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NAME 

K_set_priv 


MODULA  SYNOPSIS 

CONST  obISeid:  geld; 

CONST  priv:  oriv  struct: 

VAR  scat:  K  err  tium; 

stat  : “  NK  set  priv(ob1Seld,  priv) ; 


C  SYNOPSIS 

seid  obISeid; 
priv  struct  priv; 
int  scat ; 

stat  *  K  set  priv(objSeid.  priv) ; 

DESCRIPTION 

K  set  priv  sets  the  privileges  of  the  object  specified  by  the  first  argu¬ 
ment  to  the  privileges  specified  by  the  second  argument* 
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NAME 

K_set_procdSs_statu8 

MODULA  SYNOPSIS 

CONST  procSeid :  geld ; 

CONST  status:  proc  stat  block: 

CONST  choice:  selector : 

VAR  stat:  R  err  nua; 

•  •  • 

stat  : -  NK  set  process  status (procSeid.  status .  choice) ; 


C  SYNOPSIS 

seid  procSeid: 
proc  stat  block  status : 
selector  choice; 
int  stat ; 

stat  -  K  set  process  status  (procSeid.  & status,  choice) ; 

DESCRIPTION 

The  K  set  process  status  call  permits  the  process  to  change  those  type 
dependent  parameters  that  are  not  controlled  by  other  primitives. 

The  K  set  process  status  Kernel  call  supplies  an  advisory  scheduling 
priority  to  the  Kernel  level  scheduler.  The  Kernel  may  elect  to  adjust 
the  advisory  priority  to  guarantee  equitable  service  to  all  processes. 

The  notion  of  real  and  effective  user  identification  shall  be  retained  at 
the  Kernel  level  because  these  identifiers  determine  the  access  permis¬ 
sions  extended  to  a  process-  The  effective  user  and  group  ID's  are  part 
of  the  type  independent  information  for  the  process,  because  they  are 
what  determine  the  discretionary  access  rights.  The  real  user  and  group 
ID's  are  part  of  this  type  dependent  information  and  require  the 
privilege  privSetLevel  to  modify. 

The  timer  toggle  and  pseudo  interrupt  level  control  the  pseudo  interrupt 
mechanism.  If  the  timer  toggle  is  TRUE,  a  pseudo  interrupt  shall  be  gen¬ 
erated  every  clock  tick  (machine  dependent  time  unit).  This  mechanism 
may  be  used  for  periodic  sampling  of  user  mode  program  counter  values  for 
the  construction  of  execution  profiles.  The  pseudo  interrupt  level  is 
analogous  to  the  hardware  interrupt  level.  Pseudo  interrupts  shall  be 
transmitted  to  the  process  only  if  the  level  of  the  pseudo  interrupt  is 
above  the  level  of  the  process. 
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NAME 

K_se  C_segmen  t_s  ta  tua 

MODULA  SYNOPSIS 

CONST  segSeid :  seid ; 

CONST  status :  see  stat  block; 

CONST  choice:  selector: 

VAR  stat :  K  err  num; 

stat  NK  set  segment  status (segSeid.  status,  choice); 


C  SYNOPSIS 

seid  segSeid; 
egg  stat  block  status : 
choice  selector; 
int  stat ; 

«  «  « 

stat  “  K  set  segment  status  (segSeid.  Astatus.  selector) ; 

DESCRIPTION 

K  set  segment  status  supports  modification  of  the  type  dependent  informa¬ 
tion  of  a  segment.  The  invoking  process  shall  have  appropriate  privilege 
in  order  to  modify  the  "sticky"  flag  or  the  "lock"  flag. 
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NAME 

K_signal 

MODULA  SYNOPSIS 

CONST  procSeld:  said; 

CONST  sIgMsg:  mag  struct; 

VAR  stat :  K  err  num; 

stat  :»  NK  signaHprocSeld.  sigMsg) : 


C  SYNOPSIS 

sgid  procSeld; 
mag  struct  sigMsg; 
lot  stat; 

•  •  • 

stat  -  K  signal  (procSeld,  AsigMsg) ; 


DESCRIPTION 

The  K  signal  primitive  provides  a  means  for  privileged  processes  to 
transmit  a  high  priority  pseudo-interrupt  to  a  process*  K  signal  differs 
from  the  K  post  IPC  mechanism  in  several  ways.  First,  K  signal  always 
generates  a  pseudo  interrupt.  The  pseudo- interrupt  level  of  the  K  signal 
pseudo-interrupt  is  above  that  of  normal  IPC.  Second,  the  K  signal  pseu¬ 
do  interrupt  will  abort  long  running  Kernel  calls  (i.e.  terminal  I/O) 
which  receiving  the  K  post  mechanism  does  not.  The  intended  use  of 
K  signal  is  to  provide  a  mechanism  for  a  privileged  process  to  "get 
through"  to  another  process,  typically  to  ask  it  to  terminate.  The  Cal¬ 
ling  process  must  have  the  privilege  privSignal- 
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NAME 

K_spavn 

MODULA  SYNOPSIS 

CONST  immSeid:  seid ; 

CONST  arg;  sag  das; 

VAR  child;  seid; 

VAR  stat ;  K  err  nun; 

a tat  : ■  NK  spawn (jtimSeid,  arg.  child) ; 


C  SYNOPSIS 

seid  immSeid ; 
sag  des  arg; 
seid  child; 
int  stat ; 

•  •  « 

stat  “  K  spawn  (immSeid,  arg.  Achild) ; 

DESCRIPTION 

The  Kernel  primitive  K  spawn  combines  the  functions  of  K  fork  and 
K  invoke  into  one  operation.  The  K  spawn  primitive  permits  process  crea¬ 
tion  without  the  cost  of  copying  the  parent  process  image  to  the  child 
process.  The  effect  of  K  spawn  is  to  create  a  new  process  and  to  force 
the  effect  of  a  K  invoke  call  upon  the  newly  created  process.  The  parent 
process  may  therefore  completely  specify  the  contents  of  the  child  pro¬ 
cess  image. 

The  parameters  to  K  spawn  are  the  same  as  the  parameters  to  the  K  invoke 
primitive.  These  parameters  are  used  to  determine  the  effect  of  the 
K  invoke  call  forced  upon  the  child  process.  (See  K  invoke  above  for  a 
discussion  of  this  primitive.)  The  full  semantics  of  K  invoke  are  imple¬ 
mented.  Hence,  a  child  process  may  acquire  more  privilege  than  the 
parent  and  may  operate  in  a  different  discretionary  access  domain. 

SEE  ALSO 

R_invoke(II) 
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NAME 

K_sp  ecia l_f  unc  t ion 
DESCRIPTION 

This  Kernel  call  has  been  deleted. 
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NAME 

K_unlink 

MODULA  SYNOPSIS 

CONST  fSeid:  seid; 

VAR  Btat;  K  err  nan; 

•  •  • 

stat  :■  NK  unlink(fSeid) ; 


C  SYNOPSIS 

seid  fSeid; 
int  stat : 

•  •  • 

stat  “  K  unlink  (fSeid) ; 

DESCRIPTION 

K  unlink  decrements  the  file  reference  count  of  the  specified  file.  When 
the  file  reference  count  is  zero  and  no  process  has  the  file  open,  the 
file  is  deleted.  When  the  count  is  decremented  from  one  to  zero,  the 
file  becomes  logically  nonexistent*  If  a  file  is  logically  nonexistent, 
but  the  file  has  not  been  deleted  because  some  process  still  has  it  open, 
it  cannot  be  opened  again,  and  the  file  does  not  exist  for  Kernel  calls 
which  take  file  SEIDs  as  arguments,  such  as  K  link (II).  When  a  file  is 
created  with  K  create (II)  it  has  a  reference  count  of  zero,  but  does  have 
logical  existence  and  thus  K  link (II)  can  be  used  to  increment  its  count* 

The  security  and  integrity  checking  are  as  if  the  file  is  being  opened 
for  reading  and  writing,  except  that  no  discretionary  access  checking  is 
done  by  the  Kernel,  allowing  processes  privileged  to  use  this  primitive 
to  perform  whatever  checking  they  choose  to. 

The  use  of  K  unlink  requires  the  privilege  privLink.  This  privilege  is 
normally  restricted  to  the  UNIX  directory  manager. 
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NAME 

K_unmount 

MODULA  SYNOPSIS 

CONST  nsp :  nsp  type ; 

VAR  stat:  K  err  num: 

atat  :■  NK  unmount (nap ) : 


C  SYNOPSIS 

nap  type  nsp ; 
int  atat; 

atat  »  K  unmount  (nap) ; 


DESCRIPTION 

The  Kernel  primitive  K  unmount  logically  unmounts  the  file  system  speci¬ 
fied  by  the  name  space  partition  nsp.  The  following  checks  must  be 
satisfied  before  the  Kernel  will  unmount  a  file  system: 

*  the  process  must  have  the  privilege  to  issue  the  call 

*  the  device  must  have  file  system  mounted  on  it 

*  the  extent  must  be  tranquil  (no  open  files) 


After  normal  completion  of  the  Kernel  call,  the  disk  has  been  returned  to 
the  'unmounted'  condition  and  can  be  mounted  again  in  the  future  without 
performing  file  recovery. 

Should  a  disk  device  fail  and  have  to  be  shut  down,  it  is  still  possible 
to  perform  a  K  unmount  to  inform  the  Kernel  that  the  file  system  is  now 
unmounted.  Although  the  K  unmount  will  return  an  I/O  error  exception 
(Xerror  or  Xfault)  the  Kernel's  internal  database  will  still  be  purged  of 
information  about  the  file  system.  This  allows  mounting  the  disk  on 
another  drive  and  (after  file  system  recovery,  if  required)  remounting 
the  file  system. 

SEE  ALSO 

KSOS  Operator  /  Administrator  Reference  Manual  [reference  to  be  sup¬ 
plied) 
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NAME 

K_walk__p  roce88_table 

MODULA  SYNOPSIS 

CONST  index:  cardinal: 

VAR  p  Said:  said: 

VAR  atat:  K  err  nun; 

a  •  • 

atat  :»  NK  walk  process  table (index,  p  seid); 


C  SYNOPSIS 

cardinal  index: 
seid  p  seid; 
int  atat: 

«  •  • 

stat  ■  K  walk  process  table  (index.  &p  seid) ; 

DESCRIPTION 

The  K  walk  process  table  primitive  is  a  means  for  privileged  software  to 
obtain  the  SEIDs  of  active  processes.  The  primitive  returns  the  SEID  of 
the  process  which  occupies  slot  index  of  the  global  process  table.  This 
SEID  can  then  be  used  in  K  get  object  level  or  K  get  process  status 
calls.  The  call  fails  if  the  process  does  not  possess  the  privilege  to 
issue  it,  or  if  index  is  not  a  valid  index  number  for  the  process  table. 
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NAME 

K_write_block  -  perform  write 

MODULA  SYNOPSIS 

CONST  od :  openDescriptor ; 
CONST  blockNo:  fBlockNumber ; 
CONST  outP:  p  block: 

CONST  id:  asyncld; 

VAR  errs :  ioStatus ; 

VAR  status:  K  err  num: 


status  :-  NK  write  block(od.  blockNo.  outP.  id,  errs) ; 


C  SYNOPSIS 

openDescriptor  od: 
long  blockNo; 
pblock  outp ; 
int  id; 

ioStatus  errs; 
int  status; 

*  •  • 

status  -  K  write  block(od.  blockNo.  &outp .  id.  &errs) ; 


DESCRIPTION 

K  write  block  is  used  to  request  writing  to  files,  terminals,  extents, 
and  devices.  The  parameter  block  outP  defines  the  memory  area  to  be  used 
for  output- 

Writing  to  a  file  will  cause  file  space  to  be  allocated  as  required.  A 
write  which  increases  the  highest  block  number  of  the  file  sets  the  byte 
size  of  the  file  to  (high  block  x  512).  The  user  may  later  indicate,  via 
the  SETFILESIZE  function  of  K  device  function(II) .  that  the  size  of  the 
file  in  bytes  is  up  to  511  less.  This  will  not  prevent  the  entire  last 
block  from  being  read. 

Piles  may  contain  "holes",  (unwritten  blocks)  but  extremely  sparse  files 
are  inefficient. 

ASYNCHRONOUS  REQUESTS 

See  K  device  function(II) .  To  make  a  normal,  synchronous,  request,  ijd 
should  be  zero. 

SEE  ALSO 

K_device_function(II) ,  K_read_block(II) 
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NAME 

Modula_Kemel_InCer face  -  Modula  Interface  to  the  Kernel  Calls 
DESCRIPTION 

Modula  interface  routines  for  the  Kernel  calls  are  available  in  the  file 
NKcalls.mod.  One  interface  routine  exists  per  Kernel  call.  The  inter¬ 
face  routines  are  used  in  conjunction  with  the  types  and  low  level  inter¬ 
face  procedures  defined  in  NEWcalls.mod 

The  general  procedure  followed  in  the  interface  routines  is  to  put  the 
arguments  into  one  contiguous  block  of  memory.  Then  through  an  assembly 
language  subroutine,  a  pointer  to  the  block  with  the  arguments  is  passed 
to  the  appropriate  kernel  call.  Upon  completion,  the  kernel  call  places 
any  return  values  into  the  argument  block  and  returns  an  exception.  This 
exception  is  then  passed  upward  by  the  assembly  language  subroutine.  The 
interface  routine  unpacks  the  return  values  from  the  argument  block  and 
returns  the  exception  to  the  calling  Modula  program. 

To  use  the  Modula  Kernel  interface  routines  include  the  file  NKcalls.mod 
at  the  beginning  of  your  Modula  program.  The  file  NEWcalls.mod  is  expli¬ 
citly  included  in  NKcalls.mod. 


FILES 


NKcalls.mod,  NEWcalls.mod 
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NAME 

aep_°p  -  operator  interface  to  the  audit  capture  process 
SYNOPSIS 

acp  op  flag  [file_name] 

DESCRIPTION 

Acp  op  is  an  operator  interface  to  the  audit  capture  process.  This 
interface  requires  one  of  the  following  flags: 

-c  Changes  the  device  to  which  the  audit  capture  messages  are  writ¬ 

ten.  If  the  messages  are  currently  written  to  a  file,  the  file 
will  be  closed  and  the  messages  will  be  diverted  to  the  console. 
This  function  enables  the  operator  to  close  all  acp  files  and, 
for  example,  unmount  the  root  file  system. 

-i  Identifies  the  file  in  which  the  acp  messages  are  currently  being 

placed . 

-p  Prints  out  the  acp  file  given  in  the  file_name  field. 

-r  Removes  the  acp  file  specified  in  the  file_name  field. 

-8  Switches  the  file  in  which  the  acp  messages  are  placed  to  a  new 

file.  The  name  of  the  current  file  is  printed  out.  The  file  is 
then  closed  and  a  new  file  is  opened.  The  name  of  the  new  acp 
file  is  also  printed. 

DIRECTORIES 

/ay a /sys Audit 
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NAME 

btcp  -  boot  copy  program 
SYNOPSIS 

btcp  packseid  [ — s]  [-0  levOboot]  [-1  levlboot)  t-k  kernelimage]  [-u  ini- 
tialimage] 

DESCRIPTION 

Btcp  copies  files  required  to  boot  a  KSOS  system  to  their  correct  place 
on  the  specified  initialized  KSOS  pack.  Btcp  is  spawned  by  the  secure 
server  at  the  request  of  a  user  running  at  OPERATOR  or  higher  security 
level . 

s  copy  the  system  security  map  to  extent  4  of  the  pack. 

0  copy  the  specified  level  0  boot  program  to  extent  1  of  the  pack. 

1  copy  the  specified  level  1  boot  program  to  extent  2  of  the  pack, 

k  copy  the  specified  kernel  image  to  its  proper  place  on  the  pack  - 

extent  5  beginning  at  block  0. 

u  copy  the  specified  initial  process  image  to  its  proper  place  on 

the  pack  -  extent  5  beginning  at  block  314. 

FILES 

/sys/dataBases/security  system  security  map. 


SEE  ALSO 

exi,  pki 


CAL (III) 


KSOS  10/7/80 


CAL(III) 


NAME 

Cal  -  change  access  level 

SYNOPSIS 

cal  [pathname] 

DESCRIPTION 

Change  access  level,  cal .  allows  a  user  to  create  an  environment  at  a  new 
security  level,  or  to  return  to  a  previously  interrupted  environment-  If 
the  "pathname"  argument  is  given,  the  level  of  the  environment  will  be 
that  of  the  file  specified  by  "pathname":  otherwise  cal  will  prompt  for  a 
new  access  level-  If  an  environment  already  exists  at  the  requested 
level,  cal  will  revert  to  that  environment;  otherwise  a  new  environment 
will  be  created. 

Like  login.  Cal  should  create  the  new  environment  by  spawning  the 
user/supervisor  domain  programs  given  for  the  user's  login  id  in  the 
user  access  authentication  database-  However,  as  an  interim  measure,  cal 
will  prompt  for  the  pathname  of  the  supervisor  domain  program  to  be 
spawned.  This  program  will  normally  be  a  UNIX  emulator. 

Each  user  environment  corresponds  to  a  different  terminal  path.  There  are 
a  fixed  number  (currently  3)  of  paths  on  which  user  environments  can  be 
created.  One  of  these  is  used  by  login  for  the  user's  initial  environ¬ 
ment;  the  remainder  are  available  for  allocation  by  cal. 


FILES 

/sys/dataBases/user  user  access  authentication  database 

/sys/dataBases /group  group  access  authentication  database 

/sys/dataBases/ terminal  terminal  profile  database 
/sys/dataBases /system  system  profile  database 

SEE  ALSO 

SSP(III),  login(III),  user(IV),  group(IV),  terminal (IV) ,  system(IV) 
DIAGNOSTICS 

"object  not  found"  "pathname"  does  not  exist 

"no  free  paths" 

"you  can  not  change  to  that  level" 
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NAME 

dpe  -  device  profile  database  editor 

SYNOPSIS 

dpe 

DESCRIPTION 

Dpe  interactively  edits  the  device  profile  database  and  is  invoked  from 
the  secure  server.  The  editor  commands  include  add,  change,  delete,  find, 
next,  print,  view,  and  quit*  A  description  of  comnand  action  follows. 

The  character  preceding  the  closing  parenthesis,  ')',  is  the  command 
code.  Any  unrecognized  character  causes  printing  of  the  command  list. 

a)dd  prompts  the  user  for  all  information  and  appends  the  new  record  to 
the  end  of  the  database.  The  following  questions  are  asked: 

Enter  name  (max  8  char): 

Enter  desired  device  name  space: 

Enter  desired  device  type  (high  byte): 

Enter  desired  device  unit  number  (low  word): 

Enter  user  name  of  owner  (max  8  char): 

Enter  login  name  of  group  (max  8  char): 

Does  this  device  allow  Valid_required  ?  (y  or  n)  : 

Can  user  assign  with  assign  function  ?  (y  or  n)  : 

Enter  desired  discretionary  access  for  owner: 

Enter  desired  discretionary  access  for  group: 

Enter  desired  discretionary  access  for  all: 

ENTER  ACCESS  LEVEL  DEFAULT 

SECURITY  CATEGORY 

Enter  desired  SECURITY  category: 

INTEGRITY  CATEGORY 

Enter  desired  INTEGRITY  category: 

Enter  numbers  of  desired  security  compartments 
separated  by  spaces  (carriage  return  for  NULL): 

c) hange  changes  a  specific  field  in  tha  current  record.  Change  accepts 
the  following  commands: 

ex)  it 

v)iew 

n)ame 

s)eid 

g)roup  id 

d)iscret  access 

a)cces8  level 

r)valrequr 

1 Assignment  allowed 

d) elete  the  current  record  by  asking  "Do  you  want  to  delete  [current 
record  name)  (y  or  n)  :" 

p)rint  the  current  database  records,  including  modifications,  to  the 
lineprinter. 


-  I  - 
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v) iew  outputs  the  current  record  to  the  terminal 

f ) ind  searches  the  database  for  the  specified  name  and  sets  the  current 
pointer  to  the  record*  The  user  is  prompted  for  the  name;  dpe  responds 
"Record  is  not  found",  if  the  name  not  in  the  database* 

n) ext  moves  the  current  pointer  is  to  the  next  record.  If  the  pointer  is 
currently  pointing  to  the  last  record,  it  is  moved  to  the  first  record. 

q)uit  ends  execution  of  the  editor*  If  modifications  were  made,  the 
question  "Do  you  want  to  save  the  updates?"  is  asked  and  a  y  or  n  is 
expected  in  response* 


FILES 

/sys/dataBases/device  device  profile  database 
/sys/dataBases/security  system  security  map 

SEE  ALSO 

SME(III),  UCE(III),  GAA(IV) ,  device(IV),  security(IV) ,  user(IV), 
group (IV) 

ERRORS 

can't  open  device  database 
can't  create  tempfile 
Can't  open  user  database 
can't  open  group  database 
can't  open  security_map 
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NAME 

exi  -  initialize  pack  extents 
SYNOPSIS 

exi  deviceSEID  f-rv] 

DESCRIPTION 

Exi  is  a  pack  initialization  tool  which  enables  the  administrative  user 
to  interactively  view,  define  and  modify  KSOS  pack  extent  map  slots.  It 
is  a  very  powerful  tool  and  should  be  used  carefully.  Exi  is  spawned  by 
the  secure  server  at  the  request  of  a  user  running  at  OPERATOR  or  higher 
security  level.  It  is  commonly  used  to  initialize  KSOS  file  systems. 

The  argument  deviceSeid  specifies  the  pack  which  is  to  be  operated  on 
(e.g.  dl/0).  The  -r  option  indicates  a  read  only  mode  of  operation  in 
which  extent  map  slots  may  be  viewed  but  not  modified.  The  -v  option 
causes  exi  to  interact  with  the  user  in  a  verbose  manner. 

Commands  which  operate  on  a  particular  extent  map  slot  may  be  optionally 
preceded  by  the  extent  number.  Specifying  extent  number  0  allows  modifi¬ 
cation  of  the  pack  master  mount  item.  If  no  extent  number  is  supplied 
the  current  extent  is  assumed.  Recognized  commands  include: 

[n]v  View  the  specified  extent  map  slot.  A  formatted  dump  is  pro¬ 
duced  . 

[n]f  Free  the  extent. 

1  List  extents.  The  extent  label,  first  block  number,  last  block 

number  and  extent  size  for  each  extent  on  the  pack  are  displayed. 

[n]a  Add  extent.  The  user  is  prompted  for  all  the  information  neces¬ 
sary  to  create  a  new  extent.  If  desired,  exi  will  prompt  the 
user  for  information  needed  to  initialize  the  extent  as  a  KSOS 
file  system. 

e  Exit  exi. 

[n]m  Modify  extent  map  slot.  This  command  places  the  user  in  modifi¬ 
cation  mode.  Both  the  pack  master  mount  item  and  extent  items 
may  be  modified.  After  receiving  the  prompt,  the  user  types  the 
control  character  corresponding  to  the  slot  field  to  be  modified 
and  exi  responds  by  asking  for  specific  data.  To  return  to  nor¬ 
mal  mode,  type  an  empty  line  (<CR>  only).  Control  characters  for 
each  type  of  slot  are  listed  below. 

extent  item: 
v  view  extent  item. 

a  modify  access  rights,  security  and  integrity. 

1  modify  label  field, 

s  modify  subtype  field. 
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mount  item: 

v  view  mount  item  slot. 

a  modify  access,  security  and  integrity  information. 

1  modify  label  field. 

SEE 

pki,  mce 


BUGS 

Currently  EXI  opens  the  whole  pack  unexdusively.  It  opens  the  whole 
pack  because  EXI  contains  the  functionality  to  initialize  file  systems. 

It  does  not  open  the  pack  for  exclusive  use  because,  at  least  initially, 
EXI  must  be  able  to  modify  extents  residing  on  a  pack  with  a  mounted  file 
system.  EXI  should  be  split  into  two  programs  -  one  for  extent  modifica¬ 
tion  which  exclusively  accesses  the  extent  map  extent,  and  a  separate 
program  for  file  system  initialization. 


NAME 


fan  -  file  access  modifier 
SYNOPSIS 

fan  [-v]  [[key  argument]  ...  ]  filename 
DESCRIPTION 

Fam  allows  file  access  modifications  of  files  owned  by  the  user.  The 
argument  -v  puts  fam  into  an  interactive  mode  where  the  user  will  be 
prompted  for  commands,  if  no  other  arguments  other  than  the  filename  are 
given  interactive  mode  is  assumed,  also  the  -v  flag  must  always  appear 
before  any  key  arguments.  Key  flags  must  always  be  followed  by  an 
appropriate  argument . 

The  following  are  descriptions  of  the  keys  and  their  arguments. 

-d  modify  the  discretionary  access-  The  argument  following  this 

flag  must  be  an  octal  number. 

-g  change  the  group  id  of  the  file.  The  argument  following  this 

flag  must  be  a  legal  group  name. 

-o  change  the  owner  of  the  file.  The  argument  following  this  flag 

must  be  a  legal  user  name. 

-s  change  the  security  level  of  the  file.  The  argument  following 

the  flag  must  be  a  legal  security  level  name. 

-i  change  the  integrity  level  of  the  file.  The  argument  following 

the  flag  must  be  a  legal  integrity  level  name. 

-c  delete  a  compartment  from  the  compartment  set-  The  argument  fol¬ 

lowing  the  flag  must  be  a  legal  compartment  name.  mce. 

+c  add  a  compartment  to  the  compartment  set.  The  argument  following 

the  flag  must  be  a  legal  compartment  name. 

Fam  will  never  allow  the  user  to  modify  files  he  does  not  own  or 
can  not  access.  Also  the  integrity  level  of  a  file  can  never  be 
raised  above  that  of  the  user.  It  should  be  noted  that  when  a 
user  request  that  a  file  be  given  a  lower  security  level  (by 
either  changing  the  security  category  to  a  lower  one,  or  deleting 
a  compartment)  the  entire  file  will  be  displayed  before  the 
change  is  allowed. 

BUGS 


Fam  does  not  check  to  see  if  the  filesystem  maximum  level  is 
lower  than  a  security  request  being  made. 
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NAME 

fsd  -  incremental  file  system  dump 
SYNOPSIS 

fsd  filesystem  f-OvcJ  f-e  exte ntseid]  [-b  blocks]  f-d  days]  [-f  device] 
[-h  hours] 

DESCRIPTION 

Fsd  makes  an  incremental  dump  of  all  files  on  the  specified  KSOS  file 
system  which  were  changed  after  a  certain  date*  Fsd  is  spawned  by  the 
secure  server  at  the  request  of  a  user  running  at  OPERATOR  or  higher 
integrity  level.  The  save  medium  may  be  either  tape  or  an  existing  KSOS 
extent.  Fsd  opens  the  file  system  for  exclusive  use,  thus  the  file  sys¬ 
tem  must  be  unmounted. 

b  The  next  argument  is  the  maximum  size  of  the  save  tape  (or 

extent)  in  blocks. 

c  If  the  dump  tape  overflows,  increment  the  minor  device  number  and 

continue.  Normally,  you  are  asked  to  change  tapes, 
e  Dump  to  the  specified  defined  extent  instead  of  to  tape, 

d  The  next  argument  specifies  the  dump  date  as  some  number  of  days 

prior  to  the  current  date. 

f  Use  the  next  argument  as  the  save  device  instead  of  the  default 

(device_nsp,  11,  0). 

v  Print  out  the  information  in  the  dump  header. 

h  The  next  argument  specifies  the  dump  date  as  some  number  of  hours 

prior  to  the  current  date. 

0  Dump  from  the  beginning  of  time. 


DIAGNOSTICS 

Generally  errors  are  fatal.  Files  found  in  an  unSAFE  condition  are  not 
dumped,  but  the  jnode  is  dumped  and  the  high  block  field  is  set  to  0.  A 
message  to  this  effect  is  printed  for  each  bad  file  encountered. 

FILES 

/sys/dataBases/security  system  security  map 

SEE  ALSO 

fsr(l),dump(IV) 

BUGS 

The  d  and  h  options  are  not  implemented  -  all  dumps  are  from  the  beginning  of 
time.  When  dumping  to  an  extent,  fsd  could  recover  from  most  errors.  Unfor¬ 
tunately,  fsd's  approach  is  to  exit  if  anything  is  wrong. 
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NAME 

fsr  -  incremental  tile  system  restore 
SYNOPSIS 

fsr  filesystem  [-citr]  [-e  extentseid]  [-f  device] 

DESCRIPTION 

Par  is  used  to  restore  files  dumped  using  the  fad  command*  It  is  spawned 
by  the  secure  server  at  the  request  of  a  user  running  at  OPERATOR  or 
higher  level.  The  dump  tape  (or  extent)  is  read  and  files  are  copied  to 
the  file  system  specified.  The  jnode  number  of  a  restored  file  will  be 
equal  to  its  number  before  it  was  dumped.  The  latest  incremental  dump 
must  be  restored  first  onto  a  clear  file  system.  At  this  time,  jnodes 
are  created  for  all  files  on  the  filesystem  and  they  are  restore  locked 
to  prevent  their  use  for  other  purposes  (such  as  indirect  slots).  As 
previous  dumps  are  restored,  only  files  with  a  jnode  in  the  restore 
locked  state  are  actually  copied  from  the  dump  medium.  Thus ,  to  restore 
a  file  system,  the  incremental  dumps  must  be  restored  in  reverse  order  of 
that  in  which  they  were  made.  Optional  arguments  include: 

c  If  the  tape  overflows,  increment  the  minor  device  number  and  con¬ 

tinue  on  the  new  drive. 

e  Restore  from  the  specified  extent  and  not  from  tape, 

r  Reconstruct  the  system  space  of  the  file  system.  The  first 

restore  to  a  clear  extent  must  be  done  with  this  option.  This 
should  not  be  done  lightly  Since  any  existing  information  on  the 
extent  will  be  lost. 

f  Read  the  dump  from  the  tape  drive  specified  by  the  next  argument 

instead  of  from  the  default  drive  dll/O. 
t  Print  the  numbers  of  all  jnodes  restored. 

SEE  ALSO 

fsd(l) ,dump(IV) 

DIAGNOSTICS 

If  the  security  map  on  the  dump  tape  and  the  system  to  which  it  is  being 
restored  do  not  agree  fsr  sends  an  audit  capture  message  and  aborts. 


BUGS 

The  c  option  is  not  yet  implemented. 

No  audit  capture  messages  are  sent,  ever. 


GAA(V) 


KSOS  10/7/80 


GAA(V) 


NAME 

gaa  -  group  access  authentication  database  editor 

SYNOPSIS 

gaa 

DESCRIPTION 

Gaa  interactively  edits  the  group  access  authentication  database  and  is 
invoked  from  the  secure  server.  The  editor  commands  include  add,  change, 
delete,  find,  next,  print,  view,  and  quit.  A  description  of  command 
action  follows.  The  character  preceding  the  closing  parenthesis,  ')',  is 
the  command  code-  Any  unrecognized  character  causes  printing  of  the  com¬ 
mand  list. 

a)dd  prompts  the  user  for  all  information  and  appends  the  new  record  to 
the  end  of  the  database.  The  following  questions  are  asked: 

Enter  name  (max  8  char): 

Enter  password  (max  10  char): 

Enter  password  again  to  verify  : 

Enter  group  identification  number: 

Enter  user  name  of  administrator  (max  8  char): 

ENTER  MAXIMUM  ACCESS  LEVEL 

SECURITY  CATEGORY 

Enter  desired  SECURITY  category: 

INTEGRITY  CATEGORY 

Enter  desired  INTEGRITY  category: 

Enter  numbers  of  desired  security  compartments 
separated  by  spaces  (carriage  return  for  NULL): 

c) hange  changes  a  specific  field  in  the  current  record.  Change  accepts 
the  following  commands: 

ex)  it 
v)iew 
p) ass word 
g)roup  id 
a)  dm  in 

m)ax  access  level 

d) elete  the  current  record  by  asking  "Do  you  want  to  delete  [current 
record  name]  (y  or  n)  :" 

p)rint  the  current  database  records,  including  modifications,  to  the 
lineprinter . 

v)iew  outputs  the  current  record  to  the  terminal 

f )ind  searches  the  database  for  the  specified  name  and  sets  .he  Current 
pointer  to  the  record.  The  user  is  prompted  for  the  name;  gaa  responds 
"Record  is  not  found",  if  the  name  not  in  the  database. 
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n) ext  moves  the  current  pointer  is  to  the  next  record.  If  the  pointer  is 
currently  pointing  to  the  last  record,  it  is  moved  to  the  first  record. 

q)uit  ends  execution  of  the  editor.  If  modifications  were  made,  the 
question  "Do  you  want  to  save  the  updates?"  is  asked  and  a  y  or  n  is 
expected  in  response. 


FILES 

/sys/dataBases/user  user  access  authentication  database 

/sys/dataBases/group  group  access  authentication  database 

/sys/dataBases /security  system  security  map 


SEE  ALSO 

UCE(III),  SME(III) 


ERRORS 

can't  open  gaadb 
can't  create  tempfile 
can't  open  uaa 
Can't  open  security_map 
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NAME 

login  -  sign  onto  KSOS 
DESCRIPTION 

The  login  command  is  used  when  a  user  initially  signs  onto  KSOS-  When 
the  user  hits  the  attention  key  at  a  terminal  which  is  not  logged  in,  the 
secure  server  (SSP)  invokes  login  at  that  terminal- 

Login  prompts  for  a  user  name  and  password.  Echoing  is  turned  off  (if 
possible)  during  the  typing  of  the  password,  so  it  will  not  appear  on  the 
written  record  of  the  session. 

After  a  successful  login,  the  user  and  supervisor  domain  programs  speci¬ 
fied  in  the  user  access  authentication  database  (user)  should  be  entered. 
This  will  normally  be  the  UNIX  emulator.  However,  as  an  interim  measure, 
login  will  prompt  for  the  pathname  of  an  emulator. 

The  user's  security  level  will  normally  be  the  default  level  specified  in 
the  user  access  authentication  database  for  the  given  login  name.  If 
this  level  is  higher  than  the  maximum  level  of  the  terminal  or  the 
current  maximum  level  of  the  system,  the  user's  level  will  be  lowered 
accordingly  and  a  diagnostic  message  will  be  issued. 

FILES 

/sys/dataBases/user  user  access  authentication  database 

/sys/dataBases/group  group  access  authentication  database 

/sys/dataBases /terminal  terminal  profile  database 
/sys/dataBases /system  system  profile  database 

SEE  ALSO 

SIP(III),  SSP(III),  user(IV),  group(IV),  terminal (IV) ,  system(IV) 
DIAGNOSTICS 

"Login  denied,"  if  user  does  not  exist  or  wrong  password  is  given. 

"Your  maximum  level  is  too  low  to  login." 


LOGOUT (III ) 


KSOS  9/11/80 


LOGOUT (III) 


NAME 

logout  -  sign  off  from  KSOS 
DESCRIPTION 


The  logout  command  is  used  to  sign  off  from  KSOS.  If  the  user  has  any 
active  processes,  these  are  immediately  killed. 

SEE  ALSO 

SSP(III),  login (III ) 
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NAME 

nee  -  modify  KSOS  file  system  control  entries 
SYNOPSIS 

mce  deviceseid  extent  [-rvp] 

DESCRIPTION 

Mce  is  a  file  system  maintenance  tool  which  can  be  used  to  interactively 
view  and  modify  KSOS  file  system  control  slots*  The  argument  deviceseid 
specifies  the  device  on  which  the  file  system  resides  (e*g*  dl/0). 

Extent  is  a  decimal  integer  specifying  the  extent  on  which  the  file  sys¬ 
tem  resides.  By  default  mce  is  rather  verbose  and  leads  the  user  by  the 
hand;  the  -v  option  instructs  mce  to  interact  with  the  user  in  an  even 
more  verbose  mode*  The  -p  option  instructs  mce  to  print  out  the  direct 
and  indirect  pointer  table  values  when  viewing  a  jnode.  The  -r  option 
indicates  read  only  operation  where  slots  may  be  viewed  but  not  modified. 
This  option  allows  the  user  to  view  a  mounted  file  system.  Only  an 
unmounted  file  system  may  be  modified. 

Commands  which  operate  on  a  particular  slot  may  be  optionally  preceded  by 
the  slot  number.  If  no  slot  number  is  supplied  the  current  slot  is 
assumed.  Mce  considers  all  numbers  to  be  decimal,  except  where  expli¬ 
citly  stated  otherwise.  Recognized  commands  include: 

+  Increment  current  slot  by  one. 

-  Decrement  current  slot  by  one. 

[n]v  View  slot.  A  formatted  dump  of  the  contents  of  the  specified 

slot  is  produced.  Slots  of  type  Jnode,  indirect,  reserved,  free, 
mount  item,  extent  item,  and  allocation  item  are  recognized. 

[n]i[m]  Set  current  slot  to  the  slot  number  pointed  to  by  indirect 
pointer  number  m  of  the  jnode  or  indirect  slot  number  n. 

Free  the  slot.  Returns  slot  to  free  space. 

Exit  mce. 

Modify  slot.  This  command  places  the  user  in  modification  mode. 
At  this  time  jnodes,  indirects  and  mount  items  may  be  modified. 

A  special  prompt  (*)  indicates  modification  mode.  After  receiv¬ 
ing  the  prompt,  the  user  types  the  control  character  correspond¬ 
ing  to  the  slot  field  to  be  modified  and  mce  responds  by  asking 
for  specific  data.  To  return  to  normal  mode,  type  an  empty  line 
(<CR>  only).  Modifications  are  buffered  until  leaving  modifica¬ 
tion  mode,  at  which  time  the  user  may  elect  to  save  the  changes 
or  throw  them  away.  Control  characters  for  each  type  of  slot  are 
listed  below. 

jnode: 

v  view  jnode. 


[n]  f 
e 

tn]m 
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a  modify  access  rights,  security  and  integrity, 
c  modify  condition  field. 

1  modify  link  count  field, 

h  modify  high  block  field, 

p  modify  privileges, 
t  modify  tail  count  field, 

s  modify  self  field, 

i  modify  indirect  pointer  table. 

d  modify  direct  pointer  table. 

indirect  slot: 
v  view  indirect  slot, 
h  modify  home  jnode  field, 
p  modify  parent  field, 
t  modify  treeN  field, 
i  modify  indirect  pointer  table- 
d  modify  direct  pointer  table. 


mount  item: 
v  view  mount  item. 

a  modify  access,  security  and  integrity  information, 

m  modify  mounted  field. 


PRIVILEGES 

privMount  (*  temporary  *) 

privViolStarSecurity 
privViolStar Integrity 
privViolDiscrAccess 


WARNINGS 

Mce  is  a  powerful  tool.  Because  of  its  power,  it  is  also  a  very 
dangerous  tool.  A  malicious  user,  or  even  a  well-intentioned  user  who 
mistypes  a  character  could  potentially  invalidate  an  entire  file  syBtem 
or  worse. 


BUGS 


MCE  sends  no  audit  capture  messages 
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NAME 

mnt  -  mounts  a  file  system 
SYNOPSIS 

mnt  [filesystem_name  drive_no  oount_on_entry}  f-r] 

DESCRIPTION 

Mnt  logically  mounts  the  given  file  system  on  the  mount_on_entry.  To  be 
able  to  mount  a  particular  file  system,  that  file  system  must  be  listed 
in  the  immigration  data  base. 

The  first  argument,  f ilesystem_name,  contains  the  name  of  the  file  system 
to  be  mounted.  The  drive_no  argument  gives  the  drive  where  the  filesys¬ 
tem  is  located.  The  mount_on_entry  argument  is  the  complete  pathname  to 
the  entry  on  which  the  file  system  is  to  be  mounted.  This  entry  must 
already  exist.  The  -r  flag,  if  present,  indicates  that  the  file  system 
is  to  be  mounted  read  only.  Finally,  if  no  arguments  are  given,  a  list 
of  the  currently  mounted  file  systems  is  given. 

The  user  must  be  at  OPERATOR  level  or  above  to  actually  mount  a  file  sys¬ 
tem. 


FILES 

/sys/dataBases/mountTable 
/sys /dataBases / immigrat ion 

SEE 

umt(III) 
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NAME 

NKcopy  -  copy  program 

SYNOPSIS 

nkcopv 

DESCRIPTION 

NKcopy  copies  information  from  a  given  input  seid  to  a  given  output  seid. 
It  is  used  primarily  to  copy  from  tape  to  a  file;  however  it  can  be  used 
to  copy  between  any  two  objects.  This  program  is  provided  for  develop¬ 
ment  purposes  only. 

NKcopy  excepts  a  single  or  multi-file  tape.  Each  file  should  be  written 
to  tape  in  512  byte  blocks  terminated  by  a  tape  mark  (end  of  file). 

Under  UNIX  the  files  can  Just  be  cat'ed  or  cp'ed  to  tape.  Once  the  tape 

is  made  it  should  be  mounted  on  a  TUI 6  tape  drive. 

NKcopy  can  be  invoked  by  the  secure  server  to  copy  the  files  on  the  tape 

to  the  desired  files.  When  invoked  NKcopy  prompts  for  input  and  output 

seids  and  block  lengths.  Seids  should  be  given  in  the  following  format. 

name  space/  unique  id  0/  uniq  id  1 

Well  known  namespaces: 

r  -  root  name  space. 

d  -  device  name  space.  The  seid  of  the  TU16 
drive  is  d/ll /unit  number  (0,  1) 
n  -  null  name  space. 

If  a  null  output  seid  is  given  then  a  file  is  created  and  the  seid  of  the 
newly  created  file  is  printed. 

NKcopy  also  has  the  ability  to  mount  another  file  system  and  copy  the 
file  to  that  file  system. 

BUGS 

NKcopy  does  not  use  the  directory  manager.  Presently  it  is  necessary  to 
create  a  file  with  the  directory  manager  test  frame  (udm_tf),  then 
remembering  the  seid,  copy  the  input  file  to  the  newly  created  file  file. 

SEE 

UDM_TF  -  UDM  Test  Frame 
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NAME 

PBB  -  Process  Bootstrapper 
DESCRIPTION 

The  Process  Bootstrapper  may  only  be  used  by  a  process  executing  in 
supervisor  space*  It  is  an  intermediary  that  is  brought  into  execution 
via  the  K_invoke  and  K_spawn  Kernel  calls.  The  function  of  the  PBB  is  to 
replace  the  segments  of  its  process  with  segments  filled  from  the  image 
files  specified  in  the  argument  segment  passed  to  the  Bootstrapper. 

After  this  replacement  has  been  accomplished,  the  PBB  sets  the 
privileges,  sets  the  effective  user  and  group  id's,  and  transfers  control 
to  the  supervisor  domain  at  a  well-defined  location. 

The  steps  performed  when  an  invoke  or  spawn  is  executed,  using  PBB  as  the 
intermediary,  are  given  below. 

a.  The  calling  process  (via  the  spawn/invoke  interfaces  used  by  the 
NKSR)  will  construct  the  argument  segment  for  the  process 
bootstrapper.  The  argument  block  is  built  in  location  0,  user 
domain,  d-space. 

b.  It  will  then  map  the  argument  segment  out  of  its'  address  space. 

c.  K_invoke  or  K_spawn  will  be  called.  (  K_invoke  will  release  all 
of  the  calling  segments  except  the  argument  segment.  K_spawn 
will  only  instantiate  the  argument  segment.  ) 

d.  K_invoke/K_spawn  will  then  rendezvous  with  a  copy  of  the 
intermediary  segment  and  put  it  at  supervisor  domain,  i-space, 
address  0.  The  current  pc/ps  will  be  set  to  address  0  in  the 
supervisor  domain.  This  set  up  is  required  for  the  process 
bootstrapper  to  run  non-separate  ISD. 

e.  The  process  bootstrapper  will  map  the  argument  segment  into  its 
supervisor  i-space,  thus  maintaining  non-separate  I&D. 

f.  The  process  bootstrapper  will  then  build  the  invoked  supervisor 
domain  image  in  the  user  domain  and  then  map  it  out,  and  use 
K_set_segment_status  to  make  the  vitual  address  be  supervisor 
domain  instead  of  user  domain. 

g.  The  process  bootstrapper  will  then  build  the  invoked  user  domain 
image  in  the  user  domain. 

h.  The  process  bootstrapper  will  release  the  argument  segment* 

i.  The  process  bootstrapper  will  then  issue  a  K_boot  call  with  the 
segment  descriptor  of  the  intermediary  segment.  The  K_boot  Ker¬ 
nel  call  will  release  the  intermediary  segment  and  then  map  in 
the  supervisor  domain  segments  to  where  they  belong.  The  pc/ps 
will  be  set  to  address  0  in  the  supervisor  domain. 
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The  invoked  process  image  now  exists  and  is  executing* 


The  initial  process  builds  two  bootstrapper  segments:  a  user  process 
bootstrapper  and  a  secure  server  bootstrapper  segment* 

The  user  process  boostrapper  segment  is  available  to  all  users*  Die  new 
process  runs  at  the  same  level  as  the  parent  process,  and  is  given  the 
privileges  of  its'  a.out  file* 

The  secure  server  process  bootstrapper  segment  is  only  used  by  the  NKSR 
and  exists  at  system  high  level.  It  takes  a  tii  structure  as  part  of  the 
argument  block.  The  child  process  runs  with  a  tii  equal  to  that  which 
was  passed  in  the  argument  block. 

Once  the  process  bootstrapper  segments  are  built,  the  secure  initiator 
process  (SIP)  makes  directory  entries  "/sys/sysbin/userPBB”  and 
" /sy s /sysbin /server  PBB" . 
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The  user  process  bootstrapper  argument  segment  has  the  following  format: 


160014B 
+  supv_size 

args_addr  » 
160014B 

160012B 

16001 OB 

160004B 


160000B 
-  argseg_addr 


User  Domain 

—  1 

I 

1 

I 

Arguments 

1 

1 

1 

1 

Supervisor  Domain 

1 

I 

| 

Arguments 

1 

1 

1 

1 

User  arguments  size 

I  •  user_size 

Supervisor  arguments  size 

|  •  8upv_size 

User  Domain  f_seid 

i 

|  *  user  seid 

1 

Supervisor  Domain  f_seid 

1 

|  -  supv  seid 

I 

—  1 

-  3  - 
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The  secure  server  process  boocstrapper  argument  segment  has  the  following 
format: 


160014B 
+  supv_size 


args_addr  - 
160034B 

160014B 

160012B 

16001 OB 

160004B 

160000B 


User  Domain 
Arguments 


Supervisor  Domain 
Arguments 


Til 

User  arguments  size 
Supervisor  arguments  size 

User  Domain  f  seid 


Supervisor  Domain  f_seid 


"  argseg  addr 


tii 

user_size 

supv_size 

user_seid 

supv_seid 


SEE  ALSO 

SIP(III) 


tt.t, 
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pki  -  pack  initialization  program 
SYNOPSIS 

pki  packseid  [-a] 

DESCRIPTION 

Pki  initializes  the  pack  reserved  extents  on  an  uninitialized  pack.  Pki 
is  spawned  by  the  secure  server  at  the  request  of  a  user  running  at 
OPERATOR  or  higher  security  level.  The  pack  master  slot  is  initialized 
and  the  pack  is  given  the  proper  access  level.  The  pack  reserved  extents 
(extents  1-4)  are  created  and  given  the  system  subtype  and  an  access 
level  of  SYSTEMTII.  The  -a  option  indicates  that  the  user  should  be 
prompted  for  the  pack's  access  level.  The  default  level  is:  syshi  secu¬ 
rity,  syslow  integrity,  all  compartments,  NKSR  owner  and  group,  and  a 
discretionary  access  of  rvx - . 

SEE  ALSO 

exi(I) ,  btcp(I) 


KSOS  (III) 


KSOS  10/2/80 


KSOS  (III) 


NAME 

rkget  -  Get  files  from  RK05  pack. 

SYNOPSIS 

rkget 

DESCRIPTION 

Rkget  copies  files  from  a  specially  formatted  rk05  pack  to  the  specified 
KSOS  filenames.  The  user  is  prompted  for  an  rk  file  number  and  a  KSOS 
destination  file  name.  If  the  KSOS  destination  file  already  exists  it  is 
written  over;  otherwise  a  new  file  is  created.  Rkget  is  normally  used  to 
retrieve  files  written  to  the  rk  pack  using  the  UNIX  cprk  program* 


-  1  - 
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NAME 

setw  -  set  volume  valid 
SYNOPSIS 

setw  deviceseid 


DESCRIPTION 

Setw  is  a  utility  used  to  set  the  volume-valid  condition  on  the  device 
specified  by  deviceseid  (e-g-  setw  d4/0).  This  marks  a  removable  medium 
as  usable-  The  volume  valid  operation  is  accomplished  using  the 
K_device_f unction  kernel  call-  Setw  is  spawned  by  the  secure  server  at 
the  request  of  a  user  running  at  operator  or  higher  security  level- 

PRIVILEGES 


privlmmigrate 
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NAME 

gaa  -  security  map  editor 

SYNOPSIS 

sme 

DESCRIPTION 

Sag  interactively  edits  the  security  map  database  and  is  invoked  from  the 
secure  server.  The  editor  commands  include  add,  change,  delete,  level, 
print,  view,  and  quit.  A  description  of  command  action  follows.  The 
character  preceding  the  closing  parenthesis,  ')',  is  the  command  code. 

Any  unrecognized  character  causes  printing  of  the  command  list* 

a)dd  prompts  the  user  for  all  information  and  appends  the  new  record  to 
the  end  of  the  database.  The  following  questions  are  asked: 

Enter  entry  number  where  addition  is  to  be  placed: 

Enter  short  name  (max  12  char): 

Enter  long  name  (max  50  char): 

Is  this  entry  to  be  active  (yea  or  no): 

c) hange  asks  for  the  encry  number  to  be  changed.  Change  accepts  the  fol¬ 
lowing  commands: 

ex)  it 
v)iew 

s)hort  name 
Dong  name 
a) ctive 

d) elete  asks  for  the  entry  number  to  be  deleted. 

p) rint  the  current  database  records,  including  modifications,  to  the 
lineprinter . 

v)iew  outputs  the  current  level  records  to  the  terminal 

q) uit  ends  execution  of  the  editor.  If  modifications  were  made,  the 
question  "Do  you  want  to  save  the  updates?"  is  asked  and  a  "y"  or  "n"  is 
expected  in  response. 


FILES 

/sys/dataBase3 /security  system  security  map 

SEE  ALSO 

security(IV) 

ERRORS 

can't  open  security  map  database 
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NAME 

spe  -  system  profile  editor 

SYNOPSIS 

spe 

DESCRIPTION 

Spe  interactively  edits  the  system  profile  database  and  is  invoked  from 
the  secure  server.  The  editor  commands  include  quit,  view,  print,  and 
change  of  various  fields.  A  description  of  command  action  follows.  The 
character  preceding  the  closing  parenthesis,  ')',  is  the  command  code. 
Any  unrecognized  character  causes  printing  of  the  command  list* 

q)uit  ends  execution  of  the  editor*  If  modifications  were  made,  the 
question  "Do  you  want  to  save  the  updates?"  is  asked  and  a  "y"  or  "n"  is 
expected  in  response. 

v)iew  outputs  the  record  to  the  terminal 

p)rint  has  not  been  implemented. 

Change  accepts  the  following  commands: 
s)ys  name 
i)nst  name 
sys  n)um 
ve(r)sion  num 
gen  d)ate 
m)ax  acc  lev 
c)urr  max  acc  lev 
min  l)ogin  acc  lev 

The  three  access  level  fields  have  the  following  dialog  with  the  user: 

SECURITY  CATEGORY 

Enter  desired  SECURITY  category: 

INTEGRITY  CATEGORY 

Enter  desired  INTEGRITY  category: 

Enter  numbers  of  desired  security  compartments 
separated  by  spaces  (carriage  return  for  NULL): 

ENTER  MAXIMUM  ACCESS  LEVEL 

SECURITY  CATEGORY 

Enter  desired  SECURITY  category: 

INTEGRITY  CATEGORY 

Enter  desired  INTEGRITY  category: 

Enter  numbers  of  desired  security  compartments 
separated  by  spaces  (carriage  return  for  NULL): 


FILES 

/sys/dataBases/system  system  profile  database 
/sys/dataBases/security  system  security  map 
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SEE  ALSO 

SHE (III) <  syatem(IV) ,  security(lV) 
ERRORS 

can't  open  sysdb 
can't  create  tempfile 
can't  open  security__map 
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NAME 

SSP  -  secure  server  process 
DESCRIPTION 

The  secure  server  is  essentially  a  rudimentary  command  interpreter  which 
allows  a  user  to  execute  programs  ("services")*  One  secure  server  is 
spawned  for  each  configured  terminal  on  the  system.  When  the  secure 
attention  key  is  struck,  the  secure  server  responds  by  either  invoking 
login  or  by  prompting  for  a  command  if  someone  is  already  logged  in*  The 
server  prompt  is  ">  ".  The  environment  active  when  the  secure  attention 
key  is  struck  is  suspended.  Typing  a  carriage  return  in  response  to  the 
server  prompt  will  resume  the  interrupted  environment* 

Server  commands  are  just  a  single  line  of  input,  the  first  word  specify¬ 
ing  the  particular  service  to  be  performed.  The  remainder  of  the  line  is 
passed,  uninterpreted  by  the  server,  as  an  argument  to  the  requested  ser¬ 
vice*  The  server  provides  limited  editing  capabilities  on  terminal 
input:  backspacing  will  erase  single  characters,  and  an  '<?'  will  erase 
the  whole  line. 

Some  commands  such  as  change  access  level  (  cal  )  and  logout  are  inter¬ 
preted  directly  by  the  server.  The  remainder  are  the  file  names  of  pro¬ 
grams  which  are  in  the  server's  program  directories. 

The  server  only  permits  one  service  to  be  executing  at  any  one  time,  and 
an  attempt  to  execute  more  than  one  concurrently  will  produce  a  diagnos¬ 
tic  message.  An  interim  feature  of  the  server  is  the  kill  command,  which 
peremptorily  kills  any  service  the  user  is  currently  executing. 


FILES 


/sys /data Bases /user  user  access  authentication  database 
/ays /dataBases /group  group  access  authentication  database 
/sys /dataBases /terminal  terminal  profile  database 

system  profile  database 
a  server  program  directory 
a  server  program  directory 
a  server  program  directory 


/sys /dataBases /system 
/ ay 8 / server / admin 
/sys /server /operator 
/ sys / server /user 


SEE  ALSO 

SIP(III),  login(III)  ,  cal(III) ,  logout (III),  user (IV),  group(IV), 
terminal (IV) ,  system(IV) 


DIAGNOSTICS 

"service  still  executing" 
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NAME 

stc  -  storage  consistency  check 
SYNOPSIS 

stc  deviceseid  extent 
DESCRIPTION 

Stc  examines  the  KSOS  file  system  residing  on  the  specified  extent  and 
reports  any  inconsistencies* 

Diagnostic  messages  report  on  the  following  inconsistencies: 

-  Blocks  claimed  by  more  than  one  jnode  or  the  free  list. 

-  Blocks  or  slots  outside  the  range  of  the  file  system. 

-  Lost  blocks  and  slots. 

-  Bad  file  condition. 

-  Incorrect  file  size. 

Upon  completion  ate  outputs  the  following  summary  information: 

Total  files  on  the  system. 

Total  blocks  on  the  system. 

9  blocks  allocated. 

9  of  free  blocks. 

9  of  lost  blocks* 

9  of  duplicated  blocks* 

Total  slots  defined. 

9  slots  allocated. 

9  free  slots. 

9  lost  slots. 

9  duplicate  slots* 

SEE  ALSO 
mce 

BUGS 

No  scratch  file  is  used,  so  the  size  of  a  system  which  can  be  checked  is 
limited. 

No  audit  capture  messages  are  ever  sent. 
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NAME 

tpe  -  terminal  profile  database  editor 

SYNOPSIS 

tpe 

DESCRIPTION 

Tpe  interactively  edits  the  group  access  authentication  database  and  is 
invoked  from  the  secure  server*  The  editor  commands  include  add,  change, 
delete,  find,  next,  print,  view,  and  quit*  A  description  of  command 
action  follows.  The  character  preceding  the  closing  parenthesis,  ')',  is 
the  command  code*  Any  unrecognized  character  causes  printing  of  the  com¬ 
mand  list* 

a)dd  prompts  the  user  for  all  information  and  appends  the  new  record  to 
the  end  of  the  database*  The  following  questions  are  asked: 

Enter  tty  id: 

Is  the  terminal  configured  ?  (y  or  n)  : 

Is  the  terminal  to  be  treated  as  a  console  ?  (y  or  n)  : 

Enter  default  transmission  baud  rate: 

Enter  default  receiveing  baud  rate: 

Enter  default  parity  (even,  odd,  or  none)  : 

Enter  clear  screen  sequence  (max  8  chars)  : 

ENTER  MAXIMUM  ACCESS  LEVEL 

SECURITY  CATEGORY 

Enter  desired  SECURITY  category: 

INTEGRITY  CATEGORY 

Enter  desired  INTEGRITY  category: 

Enter  numbers  of  desired  security  compartments 
separated  by  spaces  (carriage  return  for  NULL): 

Ohange  changes  a  specific  field  in  the  current  record.  Change  accepts 
the  following  commands: 
ex)  it 
v)iew 
i)d 

f ) configured 
c)onsole 
t)ransmit  rate 

r) eceive  rate 
p)arity 

s) creen  clear 
m)ax  access  level 

d)elete  the  current  record  by  asking  "Do  you  want  to  delete  [current 
record  name]  (y  or  a)  :" 

p)rint  the  current  database  records,  including  modifications,  to  the 
lineprinter . 
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v)iew  outputs  the  current  record  to  the  terminal 

f )ind  searches  the  database  for  the  specified  id  and  sets  the  current 
pointer  to  the  record.  The  user  is  prompted  for  the  id;  tpe  responds 
"Record  is  not  found",  if  the  id  is  not  in  the  database. 

n)ext  moves  the  current  pointer  is  to  the  next  record.  If  the  pointer  is 
currently  pointing  to  the  last  record,  it  is  moved  to  the  first  record. 

q)uit  ends  execution  of  the  editor.  If  modifications  were  made,  the 
question  "Do  you  want  to  save  the  updates?"  is  asked  and  a  y  or  n  is 
expected  in  response. 


FILES 

/sys/dataBases /terminal  terminal  profile  database 
/sys/dataBases /security  system  security  map 

SEE  ALSO 

SME(III),  terminal(IV) ,  security(IV) 

ERRORS 

can't  open  tpdb 
can't  create  tempfile 
can't  open  security_map 
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NAME 

uce  -  user  access  authentication  database  editor 

SYNOPSIS 

uce 

DESCRIPTION 

Pee  interactively  edits  the  user  access  authentication  database  and  is 
invoked  from  the  secure  server •  The  editor  commands  include  add,  change, 
delete,  find,  next,  print,  view,  and  quit*  A  description  of  command 
action  follows*  The  character  preceding  the  closing  parenthesis,  ')',  is 
the  command  code*  Any  unrecognized  character  causes  printing  of  the  com¬ 
mand  list* 

a)dd  prompts  the  user  for  all  information  and  appends  the  new  record  to 
the  end  of  the  database.  The  following  questions  are  asked: 

Enter  name  (max  8  char): 

Enter  password  (max  10  char): 

Enter  password  again  to  verify  : 

Can  this  owner  login  ?  (y  or  n)  : 

Enter  owners  id  number  : 

Enter  owners  group  name  : 

ENTER  ACCESS  LEVEL  FOR  LOGIN 

SECURITY  CATEGORY 

Enter  desired  SECURITY  category: 

INTEGRITY  CATEGORY 

Enter  desired  INTEGRITY  category: 

Enter  numbers  of  desired  security  compartments 
separated  by  spaces  (carriage  return  for  NULL): 

ENTER  MAXIMUM  ACCESS  LEVEL 

SECURITY  CATEGORY 

Enter  desired  SECURITY  category: 

INTEGRITY  CATEGORY 

Enter  desired  INTEGRITY  category: 

Enter  numbers  of  desired  security  compartments 
separated  by  spaces  (carriage  return  for  NULL): 

Enter  directory  pathname  (max  63  char)  : 

Enter  shell  pathname  (max  63  char)  : 

Enter  emulator  pathname  (max  63  char)  : 

c)hange  changes  a  specific  field  in  the  current  record.  Change  accepts 
the  following  commands: 
ex)  it 
v)iew 
p) as sword 
Dog  in  ok 
o)wner  id 
g)roup  name 
m)ax  access  level 
curr  a)ccess  level 
d)ir  path 
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s)hell  path 
e)inul  path 

d)elete  the  current  record  by  asking  "Do  you  want  to  delete  [current 
record  name]  (y  or  n) 

p)  rint  the  current  database  records,  including  modifications,  to  the 
lineprintar. 

v)iew  outputs  the  current  record  to  the  terminal 

f )ind  searches  the  database  for  the  specified  name  and  sets  the  current 
pointer  to  the  record.  Receives  search  string  from  "Enter  name 
Responds  "Record  not  found",  if  name  not  in  database. 

n)ext  moves  the  current  pointer  to  the  next  record.  Pointer  moved  to  the 
first  record  if  currently  pointing  to  the  last  record. 

q) uit  ends  execution  of  the  editor.  If  modifications  were  made,  the 
question  "Do  you  want  to  save  the  updates?"  is  asked  and  a  y  or  n  is 
expected  in  response - 

PILES 

/sys/dataBases/user  user  access  authentication  database 

/sys/dataBases /group  group  access  authentication  database 

/sys/dataBases /security  system  security  map 

SEE  ALSO 

GAA(III),  SME(III),  user (IV) 

ERRORS 

can't  open  uaadb 
can't  create  tempfile 
can't  open  gaa 
can't  open  security_map 
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NAME 

UDM  -  UNIX  Directory  Manager. 

DESCRIPTION 

PPM  maintains  a  UNIX-like  directory  structure  on  top  of  a  KSOS  file  sys¬ 
tem.  All  directory  operations,  creating  entries,  removing  entries  and 
searching  directories  is  supported  by  the  directory  manager  and  directory 
manager  interface  procedures. 

Directories  are  of  a  distinguished  subtype  known  as  the  directory  sub- 
type.  The  directory  subtype  is  used  to  insure  that  the  UDM  is  the  only 
process  that  is  allowed  to  write  directories.  However,  other  processes 
may  open  directories  for  reading  by  presenting  a  read  directory  subtype 
open  descriptor  to  K_open. 

Access  to  the  directory  manager  is  provided  by  the  directory  manager 
interfcae,  which  must  be  compiled  with  the  program  which  plans  to  use  it. 
The  directory  manager  interface  provides  a  procedure  call  interface  to 
the  UDM.  The  interface  handles  the  packing  of  a  UDM  argument  block,  the 
building  an  argument  segment,  the  spawning  of  the  PPM  and  the  waiting  for 
IPC  status  return. 

DEFINITIONS 

Path  Name  -  A  path  name  is  a  character  array  of  directory  names,  where 
the  character  "/”  is  used  to  separate  directory  names. 

Leaf  Name  -  The  leaf  component  of  a  path  name  is  the  last  name  in  a  path 
name. 

Starting  Directory  -  Directory  operations  take  a  path  name  and  a  starting 
directory  (seid)  as  arguments.  If  a  rooted  path  name  (a  path  name 
that  begins  with  "/")  is  given  to  a  directory  manager  interface 
procedure,  the  directory  operation  assumes  the  root  directory  as 
the  starting  directory  regardless  of  the  starting  directory  given. 

Directory  Subtype  -  The  directory  subtype  is  a  well  known  seid. 

seid  (subtype_nsp,  char (100)  cardinal  (0)) 

All  directories  are  of  directory  subtype. 

Root  Directory  -  The  seid  of  the  first  mounted  file  system,  which  is  know 
as  the  root  file  system,  is: 

seid  (root_nsp,  char(0)  cardinal  (5)) 

UDM  Event  Type  -  The  directory  manager  process  communicates  status  infor¬ 
mation  to  its  parent,  the  directory  manager  interface  procedure, 
via  an  IPC.  The  first  byte  of  the  message  portion  of  the  IPC  con¬ 
tains  the  event  type  of  the  IPC.  The  IPC  returned  from  the  direc¬ 
tory  manager  shall  always  have  event  type  26  decimal. 

UDM_error  -  UDM  error  is  an  enumerated  type  that  is  declared  in  UDM 
interface.  Its  MODULA  definition  is: 
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INTERFACE  PROCEDURE 

l'JM_mkentry  -  make  a  directory  entry 


MODULA  SYNOPSIS 

:  seid; 

:  seid: 

:  ARRAY  integer  OF  char ; 
:  boolean; 

:  UDM_error ; 


SEID_o£_dir , 

SEID_o£_entry, 
path_name, 
wait_flag) ; 

DESCRIPTION 

The  UDM  mk entry  procedure  causes  a  directory  entry  to  be  made-  Starting 
at  the  directory  specified  by  SEID  of  dir,  the  components  of  the  path 
name  path  name  are  used  to  find  subordinate  directories  until  only  a  leaf 
component  of  the  path  name  remains.  A  directory  entry  is  then  made  in 
the  parent  directory  of  the  leaf  name.  This  directory  entry  is  composed 
of  the  SEID  of  entry  and  the  leaf  component  of  path  name.  Seids  with  any 
name  space  may  be  used  as  a  SEID  of  entry.  However  seids  with  a  file 
name  space  shall  be  linked. 

The  wait  flag  specifies  if  the  directory  operation  is  to  be  synchronous 
or  asynchronous.  If  the  wait  flag  is  true  then  the  procedure  shall  not 
return  until  a  IPC  status  block  is  received  from  the  PPM. 

Note  that  files  are  created  with  a  zero  link  count  and  remain  in 
existence  so  long  as  they  are  open  or  have  a  non-zero  link  count.  There¬ 
fore,  the  proper  way  to  make  a  directory  entry  for  a  newly  created  file 
is  to  create  the  file,  call  UDM  mkantry .  and  then  close  the  file. 

DIAGNOSTICS 

UDM  mkentrv  returns  the  following  error  codes: 

UDM_no_error 

UDM_cannot_link 

UDM_entry_exists 

UDM_cannot_open_dir ec  tory 

ODM_seid_refers_to_a_directory 

UDM_cannot_link_acros8_file_systems 


CONST 

SEID_of_dir 

CONST 

SEID_of_entry 

CONST 

path_name 

CONST 

wait_flag 

CONST 

UDM_stat 

UDM_stat 

:»  UDM_mkentry 

-  3 
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INTERFACE  PROCEDURE 

UDM_mkdir  -  create  a  directory 


MODULA  SYNOPSIS 

CONST 

SEID_of_dir 

:  seid; 

CONST 

dir_name 

:  ARRAY  integer  OF  char; 

CONST 

wait_flag 

:  boolean; 

VAR 

UDM  stat 

:  UDM  error ; 

UDM_stat  UDM_mkdir  (  SEID_of_dir, 

dir_name, 
wait_flag) ; 

DESCRIPTION 

UDM  mkdir  creates  a  directory.  Starting  at  the  directory  specified  by 
SEID  of  dir  the  components  of  the  path  name  dir  name  are  used  to  find 
subordinate  directories  until  the  last  parent  directory  component  is 
found.  A  directory  is  then  created  in  the  parent  directory  with  the  name 
of  the  leaf  name-  This  newly  created  directory  shall  have  access  modes 
of  read,  write,  execute  by  owner  and  read,  execute  by  group  and  others. 
Also,  this  directory  shall  contain  two  distinguished  directory  entries, 
and  The  directory  entry  shall  refer  to  the  newly  created 

directory  and  the  directory  entry  shall  refer  to  the  parent  direc¬ 

tory. 

The  wait  flag  specifies  if  the  directory  operation  is  to  be  synchronous 
or  asynchronous.  If  the  wait  flag  is  true  then  the  interface  procedure 
shall  not  return  control  to  the  caller  until  an  IPC  status  block  is 
received  from  the  UDM. 

DIAGNOSTICS 

UDM_mkdir  returns  the  following  error  codes: 

UDM_no_error 
UDM_ent r  y_ex is t s 
UDM_canno  t_op  en_d irectory 
UDM_cannot_create_directory 
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INTERFACE  PROCEDURE 

UDM__rm  -  remove  a  directory  entry 


MODULA  SYNOPSIS 

CONST 

SEID_of  dir 

:  seid; 

CONST 

path_name 

:  ARRAY  integer  OF 

CONST 

wait_f lag 

:  boolean; 

VAR 

UDM_stat 

:  UDM_error; 

UDM_stat  :»  UBM_rm  (  SEID__o£ JDir , 

path_name , 
wait_flag) ; 


DESCRIPTION 

The  PPM  rm  procedure  caus.es  a  directory  entry,  which  may  be  a  file  or 
directory,  to  be  removed.  Starting  at  the  directory  specified  by 
SEID  of  Dir  the  components  of  the  path  name  path  name  are  used  to  find 
subordinate  directories  until  only  a  leaf  component  of  the  path  name 
remains.  The  leaf  name  directory  entry  is  then  removed.  If  the  direc¬ 
tory  entry  to  be  removed  is  a  file,  K  unlink  is  called.  If  the  directory 
entry  to  be  removed  is  an  empty  directory,  consisting  of  only  and 
entries,  the  directory  is  removed. 

The  wait  flag  specifies  if  the  directory  operation  is  to  be  synchronous 
or  asynchronous.  If  the  wait  flag  is  true  then  the  procedure  shall  not 
return  until  a  IPC  status  block  is  received  from  the  UPM. 

DIAGNOSTICS 

TOM  rm  returns  the  following  error  codes: 

UDM_no_error 

TOMn o t_f o  und 

UDM_canno  t__u  nl  in  k 

UDM_di  rectory _uot__erapty 

UDM_cannot_  open_directcry 

TOM_cannot_removu_directory 


UDM  (HI) 


kSCo  l-j/z/SO 


UDM (III) 


INTE~KFr.CE  PROCEDURE 

'uJM  £ind  -  Path  iuiwC,>rsCaUoa  . 

MODULA  SWOPS  IS 


CONST 

starting_dir__Seid 

CONST 

path  name 

AREA '/ 

CONST 

operation 

pathO 

VAR 

parent_dir  se id 

seid ; 

VAR 

entry_  seid 

seid ; 

VAR 

entry  name 

aRR  A  i 

VAR 

UDM  Slat 

JDM  e 

UDM  _s  v.  a  t 

:  -  URK  i  in  a  (s  t  a  i  u l  nt;  d 
path  name, 

r-l at.  1 
j-  •  -  •  t-ul  Cl  J~  *. 

<iui.  ty  i  d 

r  a,.  in 

f.nry_iiati)cj  ; 


DESCRIPTION 

UDM  find  performs  p<.t«  interpretati-..,-.  ions,  Starting  at  the  direc¬ 

tory  specified  by  st  at .  ii-i*  ,ii  r  sd  Ci  y  Uc  wOTU^f  one,:*. !,  of  the  path  name 
path  name  are  used  to  chad  subordinate-  . c  r  v;  it  et:  a  only  a  leaf  com¬ 
ponent  of  tuii  JJrlth  i.-iue  %  >  Till  j  jci  -/[ie*  at  lOu  e  C  —  1  1  e  C  r;V  op  e“  u- 

t j.on  is  then  performed. 

For  all  directory  operations,  if  the  path  name  to  the  parent  directory  of 
the  leaf  name  is  legal,  then  the  patent  dir  setd  :.s  filled  with  the  seid 
of  the  parent  directory  and  the  entry  name  is  filled  with  vine  leaf  name. 

If  the  entry  name  directory  entry  exists  then  entry  said  is  filled  with 

the  seid  of  that  directory  entry.. 

'flie  following  patn  operations  are  detinea: 

po  akencry  *■  cheCfts  ir  a  uiicctoiv  ant.  y  o  i  t.  Ji  e.  spec  ified  na  r«i  d  c<x.  n 
be  made.  A  status  of  PPM  n:  error  is  ret..£“>  if  the  process 
has  write  permissions  ir.  the  patent  directory  end  if  the  entry 
ot  the  deairau  name  does  no '  exist  - 

P't.  remove  -  date  u«  1  r  th-s  Or,  ....  -..r  v  .  in  -specified  name 

can  be  remoc'ei-  A  status  ot  UDM  no  iirrr  is  retr.tr, «.d  if  the 

process  has  write  per.ai.ss  inn  j  in  the  parent,  directory  and  the 
leaf  vame  directory  entry  exists-  I.-:  'he  leaf  name  is  a  direc¬ 
tory  -hat  directory  must  on.  -  om-Ac  i  n  the  1  ,-nn  " . . "  directory 
entries. 

po^locete  dele  r:n  i  i;;n  i  r  ,\  >.  ■  -  fit.y  of  tie  specified  name 

exists.  A  status  ot  'jDd  i;  •  v/jt  is  returned  n  the  entry  is 
found . 
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po_chdir  -  checks  n  the  specified  directory  entry  is  a  directory 
and  that  the  process  has  Searcn/ execute  permissions  for  that 
directory.  If  the  above  checks  are  satisfied  a  status  or 
UDM  no  error  is  returned. 

po_exeC  -  checks  it  the  specified  directory  entry  exists  and  is  an 
executable  fide.  A  status  of  UDM  no  error  is  returned  if  the 
process  has  execute  permissions  for  that  file  and  if  the  file 
contains  the  magic  numbers  of  407,  410  or  411  (octal). 


DIAGNOSTICS 

UDM_find  returns  the  roiiowing  err^t  eudes: 
DDM_no_error 
UDM_noj)a  th 
UDM_cannot_  do 
UDM_no  t_f o  und 
(JDM_e  n  t  r  y  __ex  i  s  1 1, 

UDM  not_ directory 
UDM_cannot  open  directory 
UDM  directory  not  wri table 
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USING  THE  UDM  INTERFACE 

Two  UDM  interlaces  exist,  one  ror  supervisor  MOijULa  prog  raws  and  one  ror 
supervisor  C  programs. 

To  use  the  UDM  interface  tor  MODULA  one  must: 


a)  Define  the  following  cpp  constants:  k_oldseg;  k  invoke ,  k_sp<;wii , 
k_getps ,  k_relseg,  k_getss,  k_setss,  ksetps,  and  k  setda- 
Defining  these  constants  allows  the  related  kernel  oalis  to  be 
conditionally  compiled  with  the  source. 

b)  Include  KERcalls.mad . 

c)  Define  the  cpp  constant  ipe  >i.  •  This  «.pp  constant  allows  the 
IPC  handling  procedure  to  be  complied. 

d)  Declare  the  procedure  iPC  vc. id.  This  procedure  is  imported 
into  the  ps  eu-io  inter  >  up  t  ..a*.  .li-ng  modeie  and  .  i  is  use  to 
check  the  validity  oi  an  ipc  before  it  is  put  on  the  IPC  queue- 
This  procedure  allows  a  process  to  guarantee.  that  its  IPC  queue 
will  net  get  filled  with  unwanted  IPC '» .  The  procedure, 

IPC  valid  should  take  an  me  block  as  a  parameter  and  should 
return  a  boolean  result-  True  if  the  i?C  is  to  be  placed  on  the 
queue  and  false  if  the  IPC  is  to  be  discarded. 

e)  Include  the  the  pseudo- in  t  sir?  up  c  hcudiiag  module  no  i.  mod.  f) 
Include  the  UDM  directory  manage;,  interface  for  MODULA. 


FILES 


KER.calls.mod 

udm_lib.mod 
EDI  .h 
npi.mod 


A-rnel  interlace 

-  UOh  interface  for  hOiVdl A 

-  UDM  interface  for  C 

-  Pseudo—  inter r up t  handling  mc.au le 


SEE  ALSO 

ipc_oiock  (I) 
seid  (I) 
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NAME 

udmtf  -  UDM  Test  Frame 

SYNOPSIS 

udmtf 

DESCRIPTION 

The  udmtf  allows  one  to  exercise  the  directory  manager.  It  is  often  used 
to  create  files,  which  can  be  overwritten  by  NKcopy .  Udmtf  prompts  with 
a  ">"  and  accepts  the  following  commands: 

is  [-IrT]  [directory  name]  provides  a  similar  functionality  to  the 
UNIX  Is. 

1  signifies  that  a  long  listing  is  to  be  performed. 

r  signifies  that  a  the  subdirectories  are  to  be  recur¬ 

sively  listed. 

T  aiguilles  that  the  Security  information  is  to  be 

printed. 

mkentry  creates  a  file, 

rm  removes  a  file  or  a  directory, 

mkdir  creates  a  directory, 

quit  causes  the  udatt  process  to  exit. 

BUGS 

Erase  and  kill  processing  is  not  performed  on  input. 
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NAME 

unit  -  unmounts  a  file  system 
SYNOPSIS 

umt  filesystem_name 
DESCRIPTION 

Umt  logically  unmounts  the  file  system  given  m  the  f ilesystem_name  argu¬ 
ment.  The  name  must  consist  of  a  full  pathname  to  the  file  system. 

The  user  must  be  at  OPERATOR  level  or  above  to  actually  unmount  a  file 
system. 

FILES 

/ sys / data Bases /mount Tab le 
/sys/dataBases/ immigration 

SEE 
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NAME 

device  -  device  profile  jataodae 
DESCRIPTION 


The  device  profile  data  base  contains  the  owner  and  maxinum  access  level 
for  each  device  on  the  system. 


The  moduia  definition  of  a  device  profile  database  record  Is: 


RECORD 

devlceName 

:  ARRAY  0:7  OF  char; 

SIZE 

8  bytes 

deviceSeld 

:  seid; 

£  bytes_ 

device  til 

:  tii  struct; 

16  bytes 

valid  required 

;  boolean; 

1  byte 

assign  required 

:  boolean; 

1  byte 

END; 

30  bytes 

devlceName  Name  of  tr.e  device. 

deviceSeld  Seld  of  the  device. 


devicetll  Includes  device  owner,  group  and  maximum  access  level  of 

the  device. 

valld_requlred  This  device  is  a  disk..  A  VOLUME  VALID  Kdevice  function 
is  required  on  this  device  before  the  disk  can  be 
accessed. 


assign_required  This  device  can  only  be  accessed  after  it  has  been 
assigned. 

The  device  profile  database  can  be  modified  with  the  device  profile  edi¬ 
tor  (DPE).  All  fields  of  the  device  profile  record  can  be  modified  with 
this  editor. 


This  data  base  is  read  by  the  secure  Initiator  (SIP),  assign  (ASG)  and 
deassign  (DSG). 


FILES 

/sys/dataBases /device 


SEE  ALSO 

DPE(III),  ASG(III),  DSG(III),  til  struct(I),  seid(I) 


KSOS(IV) 


KSOS  1/18/8; 


KSOS(IV) 


NAME 

dump  -  incremental  dump  format. 

DESCRIPTION 

The  f sd  and  far  programs  are  used  to  incrementally  dump  and  restore  KSOS 
file  systems.  The  dump  format  consists  of  four  sections,  each  of  which 
is  an  integral  number  of  512-byte  blocks  long:  a  one  block  dump  master, 
the  file  system's  security  map,  a  dump  map  and,  finally,  the  jnodes  and 
data  blocks  for  each  file  dumped.  The  complete  dump  is  written  out  as 
one  long  record  composed  of  logical  512-byte  blocks.  The  first  block  has 
the  following  structure: 

dump_master  =*  RECORD 

mount  :  mountltem  (*  fs  mount  item  -  102  bytes  *) 

from_date  :  timeStamp;  (*  incremental  dump  date  *) 
dump_date  :  timeStamp;  (*  date  this  dump  was  taken  *) 
size  :  cardinal32;  (*  blocks  used  on  save  device  *) 

secmap_size  :  cardinal'  (*  security  map  size  (blocks)  *) 
filler  :  ARRAY  1:DMJ?ILLSZ  OF  char;  (*  filler  *) 
checksum  :  cardinal;  (*  block  checksum  *) 

END; 

The  security  map  is  a  copy  of  the  security  map  database  for  the  KSOS  sys¬ 
tem  on  which  the  file  system  resides.  Its  size  is  specified  by 
secmap_size  and  is  normally  8  blocks  long.  The  dump  map  contains  one 
boolean  element  for  each  slot  in  the  system  space  of  the  file  system.  It 
indicates  which  file  system  slots  contain  JnodeS.  It  is  essentially  a 
copy  of  the  file  system  allocation  map  minus  references  to  indirect 
items.  Its  size  (in  blocks)  is  equal  to  (total  system  slots) / ( 51 2 *8  bits 
per  block)  rounded  up.  The  rest  of  the  tape  is  made  up  of  the  data 
blocks  for  each  dumped  file.  Each  set  of  data  blocks  is  immediately  pre¬ 
ceded  by  a  block  containing  the  jnode  for  the  file.  These  Jnode  blocks 
each  contain  a  dump  block  number  and  a  checksum.  The  final  block  on  the 
tape  has  a  dump  block  number  of  0. 


GROUP (IV) 
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GROUP(IV) 


NAME 

group  -  group  access  authentication  database 
DESCRIPTION 


The  group  access  authentication  database  contains  group  identification, 
administrator  and  maximum  access  level  Information. 

The  modula  definition  of  a  group  access  authentication  database  record 
is : 


RECORD 

groupName  :  ARRAY  0: 1_  0£  char; 

groupPassword  :  ARRAY  0: 10  OF  char; 

groupld  :  cardinal ; 

maxLevel  :  access  level  type; 

group Ad min  :  integer ; 

END;  . . . 

groupName  name  of  the  group 


SIZE 
S  bytes 
12  bytes 
2  bytes 
6^  bytes 
2  bytes 


30  bytes 


groupPassword  encoded  password  of  the  group 


group id 

maxLevel 

groupAdmin 


unique  group  identification  number 

maximum  access  level  of  the  group 

a  user  that  serves  as  the  group  administrator 


The  group  access  authentication  database  can  be  modified  with  the  user 
control  editor  (UCE).  All  fields  of  the  group  access  authenti f ication 
record  can  be  modified  with  this  editor. 

The  data  base  is  read  by  the  secure  server  (SSP),  and  file  access  modifi¬ 
cation  (FAM). 


FILES 

/sys /databases /group 


SEE  ALSO 

UCE (II I ) ,  SSP(III),  FAM(III),  access_level_type(I) 


SECURITY(IV) 


K.SGS  9/29/80 


SECURITY(IV) 


security  -  security  map  database 
DESCRIPTION 

The  security  map  database  specifies  the  defined  security  levels, 
integrity  levels  and  security  compartments  of  the  system. 

The  security  map  database  is  divided  into  three  sections.  There  are  16 
security  level  entries,  16  integrity  level  entries,  and  32  security  com¬ 
partment  entries. 

The  modula  definition  of  a  security  map  database  record  is: 

RECORD  SI2E 

shortName  :  ARRAY  0:11  OF  char;  12  bytes 

longName  :  ARRAY  0 : 49  OF  char;  50  bytes 

f lllnull  :  char;  l  byte 

active  :  char;  1  byte 

END;  - 


shortName  is  in  uppercase  and  does  not  need  to  end  with  null. 

longName  is  uppercase,  may  include  blanks,  and  must  end  with 

null . 

active  is  'A'  active  or  'I'  inactive. 

The  map  has  64  entries:  0-15  are  security  level  categories,  16  -  31  are 
integrity  level  categories,  and  32  -  63  are  security  compartments. 

The  security  map  database  can  be  modified  with  the  security  map  editor 
(SME).  All  fields  of  the  security  map  record  can  be  modified  with  this 
editor. 


FILES 


/sys /databases /security 


SEE  ALSO 

SME(III) 


SYSTEM/ IV) 
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SYSTEM/ IV) 


NAME 

system  -  system  profile  database 


DESCRIPTION 

The  system  profile  database  contains  system  identification  and  access 
level  information. 


The  modula  definition  of  a  system  profile  database  record  is: 


RECORD  SIZE 


sys  name 
inst  name 
sys  no 
version 
gen  date 

: -ARRAY  0:59  OF  char; 

: ARRAY  0:59  OF  char; 

: cardinal ; 

: versionType ; 

: cardi nal32; 

60  bytes 
60  bytes 

2  bytes 
A  bytes 
4  bytes 

systemMax 

:acce ss  level  type; 

6  bytes 

currentMax 

••access  level  type; 

6  bytes 

currentMi nMax 

:access  level  type; 

6  bytes 

END; 

148  bytes 

sys  name 
Inst  name 
sys  no 
version 
gen  date 

systemMax 

current Max 
currentMinMax 


system  name  for  this  system 

name  of  installation  where  this  system  is  located 

unique  KSOS  system  number 

KSOS  OS  version  number  (ma jor /minor ) 

KSOS  OS  system  generation  date  (ticks  since  January  1, 
1980) 

max  level  ever  yermitted  for  this  system 
max  level  currently  permitted  on  this  system 
defines  the  lowest  maximum  level  needed  to  login  in 
(i.e.  if  a  user's  max  level  is  less  than  this  level  he 
can  not  login) 


The  system  profile  database  can  be  modified  with  the  system  prorile  edi¬ 
tor  (SPE).  All  fields  of  the  system  profile  record  can  be  modified  with 
this  editor. 


The  data  base  is  read  by  file  access  modification  (FAM)  and  secure  server 
(SSP). 


FILES 

/sy 3 /dat abases /sys tern 


SEE  ALSO 

SPE(III),  FAM(III),  SSP/III),  access  level  type(I) 


TERMINAL(IV) 
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TERMINAL(IV) 


NAME 

terminal  -  terminal  profile  database 
DESCRIPTION 

The  terminal  profile  database  contains  terminal  configuration  and  access 
level  Information. 

The  modula  definition  of  a  terminal  profile  database  record  Is: 


RECORD 

SIZE 

ttyld 

: cha  r ; 

1  byte 

conflg 

: boolean; 

1  byte 

console 

:boolean; 

2  bytes 

xml  t Baud 

•.cardinal; 

2  bytes 

recBaud 

: cardinal ; 

2  bytes 

parity 

.•cardinal ; 

2  bytes 

clrScreen 

: ARRAY  1:8  OF  char; 

8  bytes 

maxLevel 

: access  level  type; 

6  bytes 

END; 

— 

24  bytes 

ttyld 

conflg 

console 

xml t Baud 

recBaud 

parity 

clrScreen 

maxLevel 


unique  terminal  Id 

terminal  Is  configured 

terminal  Is  to  be  treated  as  a  console 

default  transmit  baud  rate 

default  recleve  baud  rate 

default  parity 

sequence  required  to  clear  the  screen 
maximum  access  level  for  this  terminal 


The  terminal  profile  database  can  be  modified  with  the  terminal  profile 
editor  (TPE).  All  fields  of  the  terminal  profile  record  can  be  modified 
with  this  editor. 


The  data  base  is  read  by  the  secure  server  (SSP)  and  file  access  modifi¬ 
cation  (FAM). 


FILES 

/sy3/dataBases/terminai 
SEE  ALSO 

TPE(III),  SSP(III),  FAM(III) 
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USER (IV) 


NAME 

user  -  user  access  authentication  database 
DESCRIPTION 

The  user  access  authentication  database  contains  user  Identification  and 
access  level  information. 

The  modula  definition  of  a  user  access  authentication  database  record  13: 


RECORD 

SIZE 

userName 

:  ARRAY  0:7  OF  char; 

8  bytes 

userPassword 

:  ARRAY  0:10  OF  char; 

12  bytes 

loginOk 

:  boolean; 

2  bytes 

maxLevel 

:  access  level  type; 

6  bytes 

tii 

:  tii  struct; 

16  bytes 

loginDir 

:  ARRAY  0:6.3  OF  char; 

64  bytes 

loginShell 

:  ARRAY  0:63  CF  char; 

64  bytes 

loginEmul 

:  ARRAY  0:63  OF  char; 

64  bytes 

filler 

:  ARRAY  0:19  OF  char; 

20  bytes 

END; 

256  bytes 

userName 

name  of  the  user 

userPassword 

password  of  the  user 

loginOk 

true  if  user  can  login 

maxLevel 

maxinum  access  level 

tii 

login  access  level 

loginDir 

login  directory  pathname 

loginShell 

login  shell  pathname 

loginEmul 

login  emulator  pathname 

The  user  access  authentication  database  can  be  modified  with  the  user 
control  editor  (UCE).  All  fields  of  the  user  access  authentication 
record  can  be  modified  with  this  editor. 

The  data  base  is  read  by  the  secure  server  (SSP)  and  file  access  modifi¬ 
cation  (FAM). 


FILES 

/sys /dataBases /user 
SEE  ALSO 

UCE(III),  SSP(III),  FAM(III),  til  struct(I),  access  level  type(I) 
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BREAK(VI) 


NAME 

break,  brk,  sbrk  -  change  core  allocation 

SYNOPSIS 

(break  -  17. ) 
ays  break;  addr 

char  *brk(addr) 

char  *sbrk(incr) 

DESCRIPTION 

Break  sets  the  system's  idea  of  the  lowest  location  not  used  by  the  pro¬ 
gram  (called  the  break)  to  addr  (rounded  up  to  the  next  multiple  of  5i2 

bytes).  Locations  not  less  than  addr  and  below  the  stack  pointer  are  not 
in  the  address  space  and  will  thus  cause  a  memory  violation  if  accessed. 

From  C,  brk  will  set  the  break  to  addr.  'Hie  old  break  is  returned. 

In  the  alternate  entry  sbrk,  incr  more  bytes  are  added  to  the  program's 
data  space  and  a  pointer  to  the  start  of  the  new  area  is  returned. 

When  a  program  begins  execution  via  exec  the  break  is  set  at  the  highest 

location  defined  by  the  program  and  data  storage  areas.  Ordinarily, 
therefore,  only  programs  with  growing  data  areas  need  to  use  break. 

SEE  ALSO 

exec  (II),  alloc  (III),  end  (III) 

DIAGNOSTICS 

The  c-bit  is  set  if  the  program  requests  more  memory  than  the  system 
limit  or  if  more  than  8  segmentation  registers  would  be  required  tc 
implement  the  break.  From  C,  -1  is  returned  for  these  errors. 

BUGS 

Setting  the  break  in  the  range  0177700  to  0177777  is  the  same  as  setting 

it  to  zero. 

KSOS 

Note  that  in  KSOS,  the  system's  memory  grain  size  is  512  bytes  as  opposed 
to  the  64  bytes  of  UNIX. 
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CHDIR(Vl) 


NAME 

chdir  -  change  working  directory 

SYNOPSIS 

(chdir  »  12. ) 
sys  chdir;  dirnatne 

chdir(dlrname) 
char  *dirname; 

DESCRIPTION 

D1 rname  is  Che  address  of  the  pathname  of  a  directory,  terminated  by  a 
null  byte.  Chdl r  causes  this  directory  to  become  the  current  working 
directory. 

SEE  ALSO 

chdir  (I) 

DIAGNOSTICS 

The  error  bit  (c-bit)  is  sec  if  the  given  name  is  not  that  of  a  directory 
or  is  not  readable.  From  C,  a  -1  returned  value  indicates  an  error,  0 
indicates  success. 


KSOS 


1 
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CHMOD (71) 


NAME 

chmod  -  change  mode  of  file 

SYNOPSIS 

(chmod  =  15.) 

sys  chmod ;  name;  mode 

chmod(name ,  mode) 
char  *name; 

DESCRIPTION 

'rhe  file  whose  name  Is  given  as  the  null-terminated  string  pointed  to  by 
name  has  Its  mode  changed  to  mode .  Modes  are  constructed  by  ORing 
together  some  combination  of  the  following: 

4000  set  user  ID  on  execution 
2000  set  group  ID  on  execution 
0400  read  by  owner 
0200  write  by  owner 

0100  execute  (search  on  directory)  oy  owner 
0070  read,  write,  execute  (search)  by  group 
0007  read,  write,  execute  (search)  by  others 

Only  the  owner  of  a  file  may  change  its  mode. 

SEE  ALSO 

chmod  (I) 

DIAGNOSTIC 

Error  bit  (c-bit)  sec  if  name  cannot  be  found  or  if  current  user  Is  not 
the  owner  of  the  file.  From  C,  a  -1  returned  value  indicates  an  error,  0 
indicates  success. 


KSOS 

Note  that  uid  and  gld  do  not  work  as  in  UNIX.  In  particular,  from  the 
Emulator  it  is  not  possible  to  change  the  setting  of  the  set  user  or  set 
group  ID  bits. 
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CKOWN(VI) 


NAME 

chown  -  change  owner  and  group  of  a  file 

SYNOPSIS 

(chmod  =  16.) 

sys  chown;  name;  owner 

chown (name ,  owner) 
char  *name ; 

DESCRIPTION 

The  file  whose  name  is  given  by  the  null-terminated  string  pointed  to  by 
name  has  its  owner  and  group  changed  to  the  low  and  high  bytes  of  owner 
respectively.  " 

SEE  ALSO 

hown  (VIII),  chgrp  (VIII),  passwd  (V) 

DIAGNOSTICS 

The  error  bit  (c-bit)  is  set  on  illegal  owner  changes.  From  C  a  -1 
returned  value  indicates  error,  0  indicates  success. 

KSOS 

This  system  call  is  subsumed  by  the  NKSR;  attempted  use  under  the  UNIX 
Emulator  will  result  in  an  error. 
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CLOSE (VI) 


NAME 

close  -  close  a  file 

SYNOPSIS 

(close  «*  6. ) 

(file  descriptor  in  rO) 

sys  close 

close(fildes) 


DESCRIPTION 

Given  a  file  descriptor  such  as  returned  from  an  open,  creat.,  or  pipe 
call,  close  closes  the  associated  file.  A  close  of  all  files  is 
automatic  on  exit ,  but  since  processes  are  limited  to  15  simultaneously 
open  files,  close  is  necessary  for  programs  which  deal  with  many  files. 


SEE  ALSO 

creat  (II),  open  (II),  pipe  (II) 


DIAGNOSTICS 

The  error  bit  (c-bit)  is  set  for  an  unknown  file  descriptor.  From  C  a  -1 
indicates  an  error,  0  indicates  success. 


CREAT(VI) 
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CREAT(VI) 


NAME 

treat  -  create  a  new  file 

SYNOPSIS 

(creac  =  8. ) 

sys  creat ;  name;  mode 
(file  descriptor  In  rO) 

creat (name,  mode) 
char  *name; 

DESCRIPTION 

Creac  creates  a  new  rile  or  prepares  to  rewrite  an  existing  fire  called 
name,  given  as  the  address  of  a  null-terminated  string.  If  the  file  did 
not  exlsc,  it  is  given  mode  mode .  See  chmod  (II)  for  the  construction  of 
the  mode  argument. 

If  the  file  did  exist,  its  mode  and  owner  remain  unchanged  but  it  is 
truncated  to  0  length. 

The  file  is  also  opened  for  siting,  and  its  file  descriptor  is  returned 
(in  rO). 

The  mode  given  is  arbitrary;  it  need  not  allow  writing.  This  feature  is 
used  by  programs  which  deal  with  temporary  files  of  fixed  names.  The 
creation  is  done  with  a  mode  that  forbids  writing.  Then  if  a  second 
instance  of  the  program  attempts  a  creat ,  an  error  is  returned  and  the 
program  knows  that  the  name  is  unusable  for  the  moment. 

SEE  ALSO 

write  (II),  close  (II),  stat  (II) 

DIAGNOSTICS 

The  error  bit  (c-bit)  may  be  set  if:  a  needed  directory  is  not  search¬ 
able;  the  file  does  not  exist  and  the  directory  in  which  it  is  to  be 
created  is  not  writable;  the  file  does  exist  and  is  unwritable;  the  file 
is  a  directory;  there  are  already  too  many  files  open. 

From  C,  a  -1  return  indicates  an  error. 

KSOS 
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CSW(VI) 


NAME 

csw  -  read  console  switches 
SYNOPSIS 

(csw  =  38.;  not  In  assembler) 

sys  csw 

getcsv(  ) 

DESCRIPTION 

The  setting  of  the  console  switches  is  returned  (in  r0). 


KSOS 

This  call  is  not  supported  by  KSOS.  Attempted  use  will  result  in  an 
error. 
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DUP(VI) 


NAME 

dup  -  duplicate  an  open  file  descriptor 
SYNOPSIS 

(dup  «  41 . ;  not  In  assembler) 

(file  descriptor  In  rO) 
ays  dup 

dup(flldes) 
lnt  flldes; 

DESCRIPTION 

Given  a  file  descriptor  returned  from  an  open,  pipe,  cr eat ,  or  port  call, 
dup  will  allocate  another  file  descriptor  synonymous  with  trie  original. 
The  new  file  descriptor  is  returned  in  rO. 

Dup  1 3  used  more  to  reassign  the  value  of  file  descriptors  than  to 
genuinely  duplicate  a  file  descriptor.  Since  the  algorithm  to  allocate 
file  descriptors  returns  the  lowest  available  value,  combinations  of  dup 
and  close  can  be  used  to  manipulate  file  descriptors  in  a  general  way. 
This  is  handy  for  manipulating  standard  input  and/or  standard  output. 

SEE  ALSO 

creat  (II),  open  (II),  close  (II),  pipe  (II) 

DIAGNOSTICS 

The  error  bit  (c-bit)  is  set  if:  the  given  file  descriptor  is  invalid; 
there  are  already  too  many  open  files.  From  C,  a  -1  returned  value  indi¬ 
cates  an  error. 


KSOS 
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EXEC(VI) 


NAME 

exec ,  axed ,  exec /  ••  execute  a  flic; 

SYNOPSIS 

(uxc-t  ii.) 

sys  exec;  name;  arg3 

name:  <...\G> 

arga:  argO;  argl;  ;  0 
argO;  <...\0> 
argl:  <-..\0> 


execl  ( r.a ac ,  a  tgii,  ntgl, 
char  *naoe,  *argC,  *argl 


«:.vec.‘'(r  ixar  a  *:gv) 
char  ’.-.iir.e; 
cfar  *a rgv |  j; 


arga,  0) 
*,  *argn; 


DESCR  LP'iiON 

Exec  overlays  the  .ailing  piocess  with  the  nameo  rile.,  then  transfers  to 
che  beginning  of  che  core  1  rage  of  the.  file.  There  can  be  no  return  fro  a 
the  file;  the  calling  core  image  Is  lost. 


files  remain  open  across  exec  calls.  Ignored  signals  remain  ignored 
across  exec,  but  signals  chat  are  caught  are  reset  to  their  default 
values . 


Each  user  has  a  real  user  ID  and  group  ID  and  an  effective  user  ID  and 
group  ID.  The  real  ID  identifies  the  person  using  the  system;  the  effec¬ 
tive  ID  determines  his  access  privileges.  Exec  changes  the  effective 
user  and  group  ID  to  the  owner  of  the  executed  file  if  the  file  uas  the 
' 'set-user-ID"  or  ' 'set-group-ID ' '  modes.  The  real  user  ID  is  not 
affected. 

The  form  of  this  call  differs  somewhat  depending  on  whether  it  is  called 
from  assembly  language  or  C;  see  below  for  the  C  version. 

The  first  argument  to  exec  is  a  pointer  to  the  name  of  the  file  to  be 
executed.  The  second  is  the  address  of  a  null-terminated  list  of 
pointers  to  arguments  tc.  be  passed  to  the  file.  Conventionally,  the 
first  argument  Is  the  name  of  the  file.  Each  pointer  addresses  a  string 
terminated  by  a  null  byte. 

Once  the  caljed  file  starts  execution,  the  arguments  are  available  as 
loliows.  The  stack  pointer  points  to  a  word  containing  the  number  of 
arguments.  Just  above  this  number  is  a  list  of  pointers  to  the  argument 
strings.  The  arguments  are  placed  as  high  as  possible  in  core. 
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EXEC (VI) 


sp->  oargs 
argO 

a-'gn 

-i 

argO:  <arg0\0> 
argn:  <argn\0> 

From  C,  two  Interfaces  are  available,  execl  is  useful  when  a  known  file 
with  known  arguments  is  being  called;  the  arguments  to  exec-1  are  the 
character  strings  constituting  the  file,  and  the  arguments;  as  in  the 
basic  call,  the  first  argument  Is  conventionally  the  same  as  the  file 
name  (or  its  last  component).  A  0  argument  must  end  the  argument  list. 

The  ixecv  version  is  useful  when  the  number  of  arguments  is  unknown  in 
advance;  the  arguments  to  exec v  are  the  name  of  the  file  to  be  executed 
and  a  vector  of  airings  containing  the  arguments.  The  last  argument 
string  musr  ce  followed  by  a  0  pointer. 

When  a  C  program  is  executed,  it  is  called  as  follows: 

main(argc,  argv) 
inc  argc; 
char  **argv; 

where  argc  is  the  argument  count  and  argv  is  an  array  of  character 
pointers  to  the  arguments  themselves.  As  indicated,  argc  is  convention¬ 
ally  at  least  one  and  the  first  member  of  the  array  points  to  a  string 
containing  the  name  of  the  file. 

Argv  is  not  directly  usable  in  another  execv,  since  argv [argc]  is  -1  and 
not  0. 

SEE  ALSO 

fork  (II) 

DIAGNOSTICS 

If  the  file  cannot  be  found,  if  it  is  not  executable,  if  it  does  not  have 
a  valid  header  (407,  410,  or  411  octal  as  first  word),  if  maximum  memory 
is  exceeded,  or  if  the  arguments  require  more  than  512  bytes  a  return 
from  exec  constitutes  the  diagnostic;  the  error  bit  (c-bit)  is  set.  From 
C  the  returned  value  is  -1. 


BUGS 

Only  512  characters  of  arguments  are  allowed. 
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NAME 

exit  -  terminate  process 


SYNOPSIS 

(exit  •  1.) 

(status  In  rO) 

ay 8  exit 

exit (status) 
lnt  status; 

DESCRIPTION 

Exit  Is  the  normal  means  of  terminating  a  process.  Exit  closes  all  the 
process's  files  and  notifies  the  parent  process  If  It  Is  executing  a 
wait .  The  low  byte  of  rO  (resp.  the  argument  to  exit )  Is  available  as 
status  to  the  parent  process. 

This  call  can  never  return. 

SEE  ALSO 

wait  (II) 

DIAGNOSTICS 

None. 


KSOS 
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NAME 

fork  -  spawn  new  process 

SYNOPSIS 

(fork  ■  2.) 
sys  fork 

(new  process  return) 

(old  process  return) 

fork(  ) 

DESCRIPTION 

Fork  is  the  only  way  new  processes  are  created.  The  new  process's  core 
image  is  a  copy  of  that  of  the  caller  of  fork.  The  only  distinction  is 
the  return  location  and  the  fact  that  rO  in  the  old  (parent)  process  con¬ 
tains  the  process  ID  of  the  new  (child)  process.  This  process  ID  is  used 
by  wait. 

The  two  returning  processes  share  all  open  files  that  existed  before  the 
call.  In  particular,  this  Is  the  way  that  standard  Input  and  output 
files  are  passed  and  also  how  pipes  are  set  up. 

From  C,  the  child  process  receives  a  0  return,  and  the  parent  receives  a 
non-zero  number  which  is  the  process  ID  of  the  child;  a  return  of  -1 
indicates  inability  to  create  a  new  process. 

SEE  ALSO 

wait  (II),  exec  (II),  sfork  (II) 

DIAGNOSTICS 

The  error  bit  (c-bit)  is  set  in  the  old  process  if  a  new  process  could 
not  be  created  because  of  lack  of  process  space.  From  C,  a  return  of  -1 
(not  just  negative)  indicates  an  error. 
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NAME 

fstat  -  get  status  of  open  file 


SYNOPSIS 

(fstat  «  28.) 

(file  descriptor  in  rO) 
sys  fstat;  buf 

fstat (flldes,  buf) 
struct  Inode  *buf; 

DESCRIPTION 

This  call  is  identical  to  stat ,  except  that  it  operates  on  open  files 
instead  of  files  given  by  name.  It  is  most  often  used  to  get  the  status 
of  the  standard  input  and  output  files,  whose  names  are  unknown. 

SEE  ALSO 

stat  (II) 

DIAGNOSTICS 

The  error  bit  (c-bit)  is  set  if  the  file  descriptor  is  unknown;  from  C,  a 
-1  return  indicates  an  error,  0  indicates  success. 

KSOS 

Not  all  fields  of  the  status  structure  are  meaningful  in  KSOS.  The  fstat 
call  supplies  zeroes  in  such  fields. 
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NAME 

getgid  -  get  group  ldenti f ications 
SYNOPSIS 

(getgid  »  47.;  not  in  assembler) 

ays  getgid 

getgid (  ) 

DESCRIPTION 

Getgid  returns  a  word  (In  rO),  the  low  byte  of  which  contains  the  real 
group  ID  of  the  current  process.  The  high  byte  contains  the  effective 
group  ID  of  the  current  process.  The  real  group  ID  Identifies  the  group 
of  the  person  who  Is  logged  In,  In  contradistinction  to  the  effective 
group  ID,  which  determines  his  access  permission  at  the  moment.  It  Is 
thus  useful  to  programs  which  operate  using  the  "set  group  ID"  mode,  to 
find  out  who  Invoked  them. 

SEE  ALSO 

setgld  (II) 

DIAGNOSTICS 

KSOS 

KSOS  group  IDs  are  16  bits  each,  but  are  mapped  Into  8  bits  by  using  only 
the  low  order  byte. 
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getpld  -  get  process  identification 
SYNOPSIS 

(getpld  «  20.;  not  in  assembler) 
sys  getpld 
(pid  in  rO) 

getpidC  ) 

DESCRIPTION 

Getpld  returns  the  process  ID  of  the  current  process.  Most  often  it  is 
used  to  generate  uniquely-named  temporary  files. 

SEE  ALSO 


DIAGNOSTICS 


Process  ids  are  unique  only  within  an  Emulator  family. 
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NAME 

getuid  -  get  user  identifications 

SYNOPSIS 

(getuid  -  24.) 

sys  getuid 

/ 

getuld(  ) 

DESCRIPTION 

Getuid  returns  a  word  (in  rO),  the  low  byte  of  which  contains  the  real 
user  ID  of  the  current  process.  The  high  byte  contains  the  effective 
user  ID  of  the  current  process.  The  real  user  ID  identifies  the  person 
who  is  logged  in,  in  contradistinction  to  the  effective  user  ID,  which 
determines  his  access  permission  at  the  moment.  It  is  thus  useful  to 
programs  which  operate  using  the  "set  user  ID"  mode,  to  find  out  who 
invoked  them. 

SEE  ALSO 

setuid  (II) 

DIAGNOSTICS 


KSOS 

KSOS  user  IDs  are  16  bits  each,  but  are  mapped  into  8  bits  by  using  only 
the  low  order  byte. 
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NAME 

gtty  -  get  terminal  status 

SYNOPSIS 

(gtty  -  32.) 

(file  descriptor  in  rO) 
sys  gtty;  arg 


arg:  .-.+6 

gtty(f i Ides ,  arg) 
int  arg [3 ] ; 

DESCRIPTION 

Gtty  stores  in  the  three  words  addressed  by  arg  the  status  of  the  type¬ 
writer  whose  file  descriptor  is  given  in  rO  (rasp,  given  as  the  first 
argument).  The  format  is  the  same  as  that  passed  by  stty . 

SEE  ALSO 

stty  (II) 


DIAGNOSTICS 

Error  bit  (c-bit)  is  set  if  the  file  descriptor  does  not  refer  to  a  type¬ 
writer.  From  C,  a  -1  value  is  returned  for  an  error,  0,  for  a  successful 
call. 


KSOS 

As  the  manipulation  of  terminal  speeds  (and  parity)  is  an  NKSR  function 
under  KSOS,  the  terminal  speed  information  returned  by  this  call  is  mean¬ 
ingless. 
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NAME 

lndlr  -  indirect  system  call 
SYNOPSIS 

(indir  -  0.;  not  in  assembler) 

sys  lndlr;  syscall 

DESCRIPTION 

The  system  call  at  the  location  syscall  is  executed.  Execution  resumes 
after  the  indir  call. 

The  main  purpose  of  indl r  is  to  allow  a  program  to  store  arguments  in 
system  calls  and  execute  them  out  of  line  in  the  data  segment.  This 
preserves  the  purity  of  the  text  segment. 

If  lndlr  is  executed  indirectly,  it  is  a  no-op.  If  the  instruction  at 
the  indirect  location  is  not  a  system  call,  the  executing  process  will 
get  a  fault. 

SEE  ALSO 

DIAGNOSTICS 


KSOS 
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INTRODUCTION  TO  SYSTEM  CALLS 


II  ot  this  manual  lists  all  the  entries  into  the  KSOS  Unix  emulator. 

In  most  cases  two  calling  sequences  are  specified,  one  of  which  is  usable  from 
assembly  language,  and  the  other  from  C.  Most  of  these  calls  have  an  error 
recurn.  From  assembly  language  an  erroneous  call  is  always  Indicated  by  turn- 
i ng  on  the  c-blt  of  the  condition  codes.  The  presence  of  an  error  is  most 
easily  tested  by  the  Instructions  bes  and  bee  ("branch  on  error  set  (or 
clear)").  These  are  synonyms  for  the  bes  and  bcc  Instructions. 


From  C,  an  error  condition  is  Indicated  by  an  otherwise  impossible  returned 
value.  Almost  always  this  is  -1;  the  individual  sections  specify  the  details. 


In  both  cases  an  error  number  is  also  available.  In  assembly  language,  this 
number  Is  returned  in  rO  on  erroneous  calls.  From  C,  the  external  variable 
errno  is  set  to  the  error  number.  Errno  is  not  cleared  on  successful  calls, 
so  It  should  be  tested  only  after  an  error  has  occurred.  There  Is  a  table  of 
messages  associated  with  each  error,  and  a  routine  for  printing  the  message. 
See  perror  (III). 


The  possible  error  numbers  are  not  recited  with  each  writeup  in  section  II, 
since  many  errors  are  possible  for  most  of  the  calls.  Here  is  a  list  of  the 
error  numbers,  their  names  inside  the  system  (for  the  benefit  of  system- 
readers),  and  the  messages  available  using  perror.  A  short  explanation  is 
also  provided. 


0  -  (unused) 


1  EPERM  Not  owner  and  not  super-user 

Typically  this  error  indicates  an  attempt  to  modify  a  file  in  some  way  for¬ 
bidden  except  to  its  owner.  It  is  also  returned  for  attempts  by  ordinary 
users  to  do  things  allowed  only  to  the  super-user. 

2  ENOENT  No  such  file  or  directory 

This  error  occurs  when  a  file  name  is  specified  and  the  file  should  exist 
but  doesn't,  or  when  one  of  the  directories  in  a  path  name  does  not  exist. 

3  ESRCH  No  such  process 

The  process  whose  number  was  given  to  signal  does  not  exist,  or  is  already 
dead. 


4  EINTR  Interrupted  system  call 

An  asynchronous  signal  (such  as  interrupt  or  quit),  which  the  user  has 
elected  to  catch,  occurred  during  a  system  call.  If  execution  is  resumed 
after  processing  the  signal,  it  will  appear  as  if  the  interrupted  system 
call  returned  this  error  condition. 


5  EIO  I/O  error 

Some  physical  I/O  error  occurred  during  a  read  or  write.  This  error  may  in 
some  cases  occur  on  a  call  following  the  one  to  which  it  actually  applies. 
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6  ENXIO  No  such  device  or  address 

I/O  on  a  special  file  refers  to  a  subdevice  which  does  not  exist,  or  beyond 
the  limits  of  the  device.  It  may  also  occur  when,  for  example,  a  tape 
drive  is  not  dialled  in  or  no  disk  pack  is  loaded  on  a  drive. 

7  E2BIG  Arg  list  too  long 

An  argument  list  longer,  than  512  bytes  (counting  the  null  at  the  end  of 
each  argument)  is  presented  to  exec. 

8  ENOEXEC  Exec  format  error 

A  request  is  made  to  execute  a  file  which,  although  It  has  the  appropriate 
permissions,  does  not  start  with  one  of  the  magic  numbers  407  or  410. 

9  EBADF  Bad  file  number 

Either  a  file  descriptor  refers  to  no  open  file,  or  a  read  (resp.  write) 
request  is  made  to  a  file  which  Is  open  only  for  writing  (resp.  reading). 

10  ECHILD  No  children 

Walt  and  the  process  has  no  living  or  unwaited-for  children. 

11  EAGAIN  No  more  processes 

In  a  fork,  the  system's  process  table  is  full  and  no  more  processes  can  for 
the  moment  be  created. 

12  ENOMEM  Not  enough  core 

During  an  exec  or  break,  a  program  asks  for  more  core  than  the  system  is 
able  to  supply.  This  Is  not  a  temporary  condition;  the  maximum  core  size 
is  a  system  parameter.  The  error  may  also  occur  if  the  arrangement  of 
text,  data,  and  stack  segments  is  such  as  to  require  more  than  the  existing 
8  segmentation  registers. 

13  EACCES  Permission  denied 

An  attempt  was  made  to  access  a  file  In  a  way  forbidden  by  the  protection 
system. 


14  -  (unused) 

15  ENOTBLK  Block  device  required 

A  plain  file  was  mentioned  where  a  block  device  was  required,  e.g.  in 
mount. 

16  EBUSY  Mount  device  busy 

An  attempt  to  mount  a  device  that  was  already  mounted  or  an  attempt  was 
made  to  dismount  a  device  on  which  there  is  an  open  file  or  some  process's 
current  directory. 

17  EEXIST  File  exists 

An  existing  file  was  mentioned  in  an  Inappropriate  context,  e.g.  link. 

18  EXDEV  Cross-device  link 

A  link  to  a  file  on  another  device  was  attempted. 

19  ENODEV  No  such  device 
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An  attempt  was  made  to  apply  an  Inappropriate  system  call  to  a  device;  e.g. 
read  a  wrlte-only  device. 

20  ENOTDIR  Not  a  directory 

A  non-directory  was  specified  where  a  directory  Is  required,  for  example  In 
a  path  name  or  as  an  argument  to  chdlr. 

21  EISDIR  Is  a  directory 

An  attempt  to  write  on  a  directory. 

22  EINVAL  Invalid  argument 

Some  Invalid  argument:  currently,  dismounting  a  non-mounted  device,  men¬ 

tioning  an  unknown  signal  In  signal ,  and  giving  an  unknown  request  In  stty 
to  the  TIU  special  file. 

23  ENFILE  File  table  overflow 

The  system's  table  of  open  files  Is  full,  and  temporarily  no  more  opens  can 
be  accepted. 

24  EMFILE  Too  many  open  files 

Only  15  flies  can  be  open  per  process. 

25  ENOTTY  Not  a  typewriter 

The  file  mentioned  in  stty  or  gtty  Is  not  a  typewriter  or  one  of  the  other 
devices  to  which  these  calls  apply. 

26  ETXTBSY  Text  file  busy 

An  attempt  to  execute  a  pure-procedure  program  which  is  currently  open  for 
writing  (or  reading!).  Also  an  attempt  to  open  for  writing  a  pure- 
procedure  program  that  Is  being  executed. 

27  EFBIG  File  too  large 

An  attempt  to  make  a  file  larger  than  the  maximum  32768  blocks. 

28  ENOSPC  No  space  left  on  device 

During  a  write  to  an  ordinary  file,  there  is  no  free  space  left  on  the  dev¬ 
ice. 


29  ESPIPE  Seek  on  pipe 

A  seek  was  issued  to  a  pipe.  This  error  should  also  be  Issued  for  other 
non-seekable  devices. 

30  EROFS  Read-only  file  system 

An  attempt  to  modify  a  file  or  directory  was  made  on  a  device  mounted 
read-only. 

31  EMLINK  Too  many  links 

An  attempt  to  make  more  than  127  links  to  a  file. 

32  EPIPE  Write  on  broken  pipe 

A  write  on  a  pipe  for  which  there  is  no  process  to  read  the  data.  This 
condition  normally  generates  a  signal;  the  error  is  returned  if  the  signal 
is  Ignored. 
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33  EMTTY  Too  many  open  TTYs  in  the  family 

An  attempt  to  open  too  many  terminals  within  the  same  eoulator  process  fam¬ 
ily.  This  error  is  a  KSOS  UNIX  Emulator  addition. 

100  ENOSYS  Nonexistent  system  call 

This  error  indicates  an  attempt  to  make  a  nonexistent  system  call. 

KSOS 

Due  to  Che  differing  internals  of  UNIX  and  the  KSOS  UNIX  Emulator,  the 
error  codes  returned  from  failed  Emulator  calls  are  frequently  only  approx¬ 
imations  Co  the  corresponding  UNIX  error  codes. 
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NAME 

kill  -  send  signal  to  a  process 
SYNOPSIS 

(kill  -  37.;  not  In  assembler) 

(process  number  In  rO) 
sys  kill;  slg 

kllKpld,  slg); 

DESCRIPTION 

Kill  sends  the  signal  slg  to  the  process  specified  by  the  process  number 
In  rO.  See  signal  (II)  for  a  list  of  signals. 

The  sending  and  receiving  processes  mist  have  the  same  effective  user  ID. 

If  the  process  number  Is  0,  the  signal  Is  sent  to  all  other  processes 
which  have  the  same  controlling  typewriter  and  user  ID. 

In  no  case  Is  It  possible  for  a  process  to  kill  Itself. 

SEE  ALSO 

signal  (II),  kill  (I) 

DIAGNOSTICS 

The  error  bit  (c-blt)  Is  set  if  the  process  does  not  have  the  same  effec¬ 
tive  user  ID,  or  If  the  process  does  not  exist.  From  C,  -1  Is  returned. 

KSOS 

Signals  have  effect  only  within  the  Emulator  family  of  the  sender. 
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NAME 

link  -  link  to  a  file 

SYNOPSIS 

(link  -  9.) 

sys  link;  namel;  name 2 

llnk(namel,  name 2) 
char  *namel,  *name2; 


DESCRIPTION 

A  link  to  namel  Is  created;  the  link  has  the  name  name 2.  Either  name  may 
be  an  arbitrary  path  name. 


SEE  ALSO 

link  (I),  unlink  (II) 


DIAGNOSTICS 

The  error  bit  (c-blt)  is  set  when  namel  cannot  be  found;  when  name 2 
already  exists;  when  the  directory  of  name 2  cannot  be  written;  when  an 
attempt  Is  made  to  link  to  a  directory;  when  an  attempt  is  made  to  link 
to  a  file  on  another  file  system;  when  more  than  127  links  are  made. 
From  C,  a  -1  return  Indicates  an  error,  a  0  return  indicates  success. 
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NAME 

mknod  -  make  a  directory  or  a  special  file 


SYNOPSIS 

(mknod  -  14.;  not  in  assembler) 

ays  mknod;  name;  mode;  addr 

■k nod (name ,  mode,  addr) 
char  *name; 

DESCRIPTION 

Mknod  creates  a  new  file  whose  name  is  the  null-terminated  string  pointed 
to  by  name.  The  mode  of  the  new  file  (including  directory  and  special 
file  bits)  is  initialized  from  mode.  The  first  physical  address  of  the 
file  is  Initialized  from  addr.  Note  that  in  the  case  of  a  directory, 
addr  should  be  zero.  In  the  case  of  a  special  file,  addr  specifies  which 
special  file. 

SEE  ALSO 

mkdir  (I),  mknod  (VIII),  fs  (V) 


DIAGNOSTICS 

Error  bit  (c-bit)  is  set  if  the  file  already  exists.  From  C,  a  -1  value 
indicates  an  error. 


KSOS 

Manipulation  of  special  files  Is  an  NKSR  function;  hence,  in  the  UNIX 
Enulator,  this  call  can  only  be  used  to  make  directories. 
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NAME 

mount  -  mount  file  system 

SYNOPSIS 

(mount  *21.) 

sys  mount;  special;  name;  rvflag 

mount (special,  name,  rvflag) 
char  *speclal,  *name; 

DESCRIPTION 

Mount  announces  to  the  system  that  a  removable  file  system  has  been 
mounted  on  the  block-structured  special  file  special;  from  now  on,  refer¬ 
ences  to  file  name  will  refer  to  the  root  file  on  the  newly  mounted  file 
system.  Special  and  name  are  pointers  to  null-terminated  strings  con¬ 
taining  the  appropriate  path  names. 

Name  mist  exist  already.  Its  old  contents  are  inaccessible  while  the  file 
system  is  mounted. 

The  rwf lag  argument  determines  whether  the  file  system  can  be  written  on; 
If  It  Is  0  writing  Is  allowed,  If  non-ztro  no  writing  Is  done.  Physi¬ 
cally  write-protected  and  magnetic  tape  file  systems  must  be  mounted 
read-only  or  errors  will  occur  when  access  times  are  updated,  whether  or 
not  any  explicit  write  Is  attempted. 

SEE  ALSO 

mount  (VIII),  umount  (II) 

DIAGNOSTICS 

Error  bit  (c-blt)  set  If:  special  Is  inaccessible  or  not  an  appropriate 
file;  name  does  not  exist;  special  Is  already  mounted;  name  Is  In  use; 
there  are  already  too  many  file  systems  mounted. 


BUGS 


KSOS 

this  call  Is  subsumed  by  the  NKSR.  Attempted  use  under  the  UNIX  Emulator 
will  result  in  an  error. 
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NAME 

nice  -  set  advisory  program  priority 

SYNOPSIS 

(nice  *■  34.) 

(priority  In  rO) 

ays  nice 

nice (priority) 

DESCRIPTION 

The  scheduling  priority  of  the  process  Is  changed  to  the  argument.  Posi¬ 
tive  priorities  get  less  service  than  normal;  0  Is  default.  The  valid 
range  of  priori ty  Is  20  to  -220.  The  value  of  4  is  recommended  to  users 
who  wish  to  execute  long-running  programs  without  flak  from  the  adminis¬ 
tration. 

The  effect  of  this  call  Is  passed  to  a  child  process  by  the  fork  system 
call.  The  effect  can  be  cancelled  by  another  call  to  nice  with  a  prior¬ 
ity  of  0. 

The  actual  running  priority  of  a  process  Is  the  priority  argument  plus  c 
number  that  ranges  from  100  to  119  depending  on  the  cpu  usage  of  the  pro¬ 
cess. 

SEE  ALSO 

nice  (I) 

DIAGNOSTICS 

The  error  bit  (c-blt)  is  set  if  the  user  requests  a  priority  outside  the 
range  of  0  to  20  and  is  not  the  super-user. 


KSOS 

This  call  is  not  yet  implemented.  The  description  of  priorities  given 
above  Is  not  accurate  for  KSOS. 
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NAME 

open  -  open  for  reading  or  writing 

SYNOPSIS 

(open  -  5. ) 

ays  open;  nane;  node 

(file  descriptor  In  rO) 

open(nane,  node) 
char  *nane; 

DESCRIPTION 

Open  opens  the  file  name  for  reading  (If  mode  Is  0),  writing  (If  mode  Is 
1)  or  for  both  reading  and  writing  (if  mode  Is  2).  Name  is  the  address 
of  a  string  of  ASCII  characters  representing  a  path  name,  terminated  by  a 
null  character. 

The  returned  file  descriptor  should  be  saved  for  subsequent  calls  to 
read,  write,  and  close. 


SEE  ALSO 

creat  (II),  read  (II),  write  (II),  close  (II) 


DIAGNOSTICS 

The  error  bit  (c-blt)  is  set  if  the  file  does  not  exist,  if  one  of  the 
necessary  directories  does  not  exist  or  is  unreadable,  if  the  file  is  not 
readable  (resp.  writable),  or  if  too  many  files  are  open.  From  C,  a  -1 
value  is  returned  on  an  error. 


KSOS 
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NAME 

pipe  -  create  an  interprocess  channel 

SYNOPSIS 

(pipe  »  42.  ) 

sys  pipe 

(read  file  descriptor  in  rO) 

(write  file  descriptor  in  rl) 

pipe(f lldes ) 
lnt  flldes[2]; 

DESCRIPTION 

The  pipe  system  call  creates  an  I/O  mechanism  called  a  pipe.  The  file 
descriptors  returned  can  be  used  in  read  and  write  operations.  When  the 
pipe  is  written  using  the  descriptor  returned  in  rl  (resp.  fildes[l]),  up 
to  4096  bytes  of  data  are  buffered  before  the  writing  process  is 
suspended.  A  read  using  the  descriptor  returned  in  rO  (resp.  fildesfO]) 
will  pick,  up  the  data. 

It  is  assumed  that  after  the  pipe  has  been  set  up,  two  (or  more) 
cooperating  processes  (created  by  subsequent  fork  calls)  will  pass  data 
through  the  pipe  with  read  and  write  calls. 

The  Shell  has  a  syntax  to  set  up  a  linear  array  of  processes  connected  by 
pipes. 

Read  calls  on  an  empty  pipe  (no  buffered  data)  with  only  one  end  (all 
write  file  descriptors  closed)  return  an  end-of-file.  Write  calls  under 
similar  conditions  generate  a  fatal  signal  (signal  (II));  if  the  signal 
is  ignored,  an  error  is  returned  on  the  write. 

SEE  ALSO 

sh  (I),  read  (II),  write  (II),  fork  (II) 

DIAGNOSTICS 

The  error  bit  (c-bit)  is  set  if  too  many  files  are  already  open.  From  C, 
a  -1  returned  value  indicates  an  error.  A  signal  is  generated  if  a  write 
on  a  pipe  with  only  one  end  is  attempted. 


BUGS 

KSOS 

This  call  is  not  yet  available. 
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NAME 

profil  -  execution  time  profile 
SYNOPSIS 

(profil  =»  44.;  not  in  assembler) 

sys  profil;  buff;  bufsiz;  offset;  scale 

profll(buff,  bufsiz,  offset,  scale) 
char  buff [  ] ; 

lnt  bufsiz,  offset,  scale; 

DESCRIPTION 

Buff  points  to  an  area  of  core  whose  length  (in  bytes)  is  given  by  buf¬ 
siz.  After  this  call,  the  user's  program  counter  (pc)  is  examined  each 
clock  tick  (60th  second);  offset  is  subtracted  from  it,  and  the  result 
multiplied  by  scale .  If  the  resulting  number  corresponds  to  a  word 
inside  buff ,  that  word  is  incremented. 

The  scale  is  interpreted  as  an  unsigned,  fixed-point  fraction  with  binary 
point  at  the  left:  177777(8)  gives  a  1-1  mapping  of  pc's  to  words  in 
buff ;  77777(8)  maps  each  pair  of  instruction  words  together.  2(8)  maps 
all  instructions  onto  the  beginning  of  buff  (producing  a  non-interrupting 
core  clock). 

Profiling  is  turned  off  by  giving  a  scale  of  0  or  1.  It  is  rendered 
ineffective  by  giving  a  bufsiz  of  0.  Profiling  is  also  turned  off  when 
an  exec  is  executed  but  remains  on  in  child  and  parent  both  after  a  fork. 

SEE  ALSO 

monitor  (III),  prof  (I) 

DIAGNOSTICS 


KSOS 

This  call  is  not  yet  implemented. 
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NAME 

pc  race  -  process  trace 
SYNOPSIS 

(ptrace  »  26.;  noc  in  assembler) 

(data  in  rO) 

sys  ptrace;  pld;  addr;  request 
(value  in  rO) 

ptrace (request,  pid,  addr,  data); 

DESCRIPTION 

Ptrace  provides  a  means  by  which  a  parent  process  may  control  the  execu¬ 
tion  of  a  child  process,  and  examine  and  change  its  core  image.  Its  pri¬ 
mary  use  is  for  the  Implementation  of  breakpoint  debugging,  but  it  should 
be  adaptable  for  simulation  of  non-UNIX  environments.  There  are  four 
arguments  whose  interpretation  depends  on  a  request  argument.  Generally, 
pld  is  the  process  ID  of  the  traced  process,  which  nust  be  a  child  (no 
more  distant  descendant)  of  the  tracing  process.  A  process  being  traced 
behaves  normally  until  it  encounters  some  signal  whether  internally  gen¬ 
erated  like  ''illegal  instruction''  or  externally  generated  like  ‘'inter¬ 
rupt.''  See  signal  (II)  far  the  list.  Then  the  traced  process  enters  a 
stopped  state  and  its  parent  is  notified  via  wait  (II).  When  the  child 
is  in  the  stopped  state,  its  core  image  can  be  examined  and  modified 
using  ptrace.  If  desired,  another  ptrace  request  can  then  cause  the 
child  either  to  terminate  or  to  continue,  possibly  ignoring  the  signal. 

The  value  of  the  request  a  gument  determines  the  precise  action  of  the 
call : 

0  This  request  is  the  only  one  used  by  the  child  process;  it  declares 
chat  the  process  is  to  be  traced  by  its  parent.  All  the  other  argu¬ 
ments  are  ignored.  Peculiar  results  will  ensue  if  the  parent  does 
not  expect  to  trace  the  child. 

1,2  The  word  In  the  child  process 's  address  space  at  addr  is  returned  (in 
rO).  Request  1  indicates  the  data  space  (normally  used);  2  indicates 
the  Instruction  space  (when  I  and  D  space  are  separated),  addr  must 
be  even.  The  child  crust  be  stopped.  The  input  data  is  ignored. 

3  The  word  of  the  system's  per-process  data  area  corresponding  to  addr 
is  returned.  Addr  must  be  even  and  less  than  512.  This  space  con¬ 
tains  the  registers  and  other  information  about  the  process;  its  lay¬ 
out  corresponds  to  the  user  structure  in  the  system. 

4,5  The  given  data  is  written  at  the  word  in  the  process's  address  space 
corresponding  to  addr,  which  must  be  even.  No  useful  value  is 
returned.  Request  4  specifies  data  space  (normally  used),  5  speci¬ 
fies  instruction  space.  Attempts  to  write  in  pure  procedure  result 
in  termination  of  the  child,  instead  of  going  through  or  causing  an 
error  for  the  parent. 
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6  The  process's  system  data  is  written,  as  it  is  read  with  request  3. 
Only  a  few  locations  can  be  written  in  this  way:  the  general  regis¬ 
ters,  the  floating  point  status  and  registers,  and  certain  bits  of 
the  processor  status  word. 

7  The  data  argument  is  taken  as  a  signal  number  and  the  child's  execu¬ 
tion  continues  as  if  it  had  Incurred  that  signal.  Normally  the  sig¬ 
nal  number  will  be  either  0  to  indicate  that  the  signal  which  caused 
the  stop  should  be  ignored,  or  that  value  fetched  out  of  the 
process's  image  indicating  which  signal  caused  the  stop. 

8  The  traced  process  terminates. 

As  indicated,  these  calls  (except  for  request  0)  can  be  used  only  when 
the  subject  process  has  stopped.  The  wal t  call  is  used  to  determine  when 
a  process  stops;  in  such  a  case  the  "termination"  status  returned  by 
wait  has  the  value  0177  to  indicate  stoppage  rather  than  genuine  termina¬ 
tion. 

To  forestall  possible  fraud,  ptrace  inhibits  the  set-user-id  facility  on 
subsequent  exec  (II) 
calls. 

SEE  ALSO 

wait  (II),  signal  (II),  cdb  (I) 

DIAGNOSTICS 

From  assembler,  the  c-bit  (error  bit;  is  Sit  on  errors;  from  C,  -1  is 
returned  and  errno  has  the  error  code. 


BUGS 

The  request  0  call  should  be  able  co  specify  signals  which  are  to  be 
treated  normally  and  not  cause  a  stop.  In  this  way,  for  example,  pro¬ 
grams  with  simulated  floating  point  (which  use  "illegal  instruction" 
signals  at  a  very  high  rate)  could  be  efficiently  debugged. 

Also,  it  should  be  possible  to  stop  a  process  on  occurrence  of  a  system 
call;  in  this  way  a  completely  controlled  environment  could  be  provided. 

KSOS 


This  call  is  not  yet  implemented. 
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NAME 

read  -  read  from  file 


SYNOPSIS 

(read  •  3.) 

(file  descriptor  in  rO) 
sys  read;  buffer;  nbytes 

read(fildes,  buffer,  nbytes) 
char  ^buffer; 


DESCRIPTION 

A  file  descriptor  is  a  word  returned  from  a  successful  open,  creat ,  dup, 
pipe ,  or  port  call.  Buffer  is  the  location  of  nbytes  contiguous  bytes 
into  which  the  input  will  be  placed.  It  is  not  guaranteed  that  all 
nbytes  bytes  will  be  read;  for  example  if  the  file  refers  to  a  typewriter 
at  most  one  line  will  be  returned.  In  any  event  the  number  of  characters 
read  is  returned  (in  rO). 

If  the  returned  value  is  0,  then  end-of-file  has  been  reached. 

SEE  ALSO 

open  (II),  creat  (II),  dup  (II),  pipe  (II) 


DIAGNOSTICS 

As  mentioned,  0  is  returned  when  the  end  of  the  file  has  been  reached. 

If  the  read  was  otherwise  unsuccessful  the  error  bit  (c-bit)  is  set. 

Many  conditions  can  generate  an  error:  physical  I/O  errors,  bad  buffer 
address,  preposterous  nbytes ,  file  descriptor  not  that  of  an  input  file. 
From  C,  a  -1  return  indicates  the  error. 


KSOS 
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NAME 

seek  -  move  read/write  pointer 

SYNOPSIS 

(seek  =*  19.) 

(file  descriptor  in  rO) 

sys  seek;  offset;  ptrname 

seek(fildes,  offset,  ptrname) 

DESCRIPTION 

The  file  descriptor  refers  to  a  file  open  for  reading  or  writing.  The 
read  (resp.  write)  pointer  for  the  file  is  set  as  follows: 

if  Ptrname  is  0,  the  pointer  is  set  to  offset. 

if  ptrname  is  1,  the  pointer  is  set  to  its  current  location  plus 
offset . 

if  ptrname  is  2,  the  pointer  is  set  to  the  size  of  the  file  plus 
offset . 


if  ptrname  is  3,  4  or  5,  the  meaning  is  as  above  for  0,  1  and  2  except 
that  the  offset  is  miltiplied  by  512. 

If  ptrname  is  0  or  3,  offset  is  unsigned,  otherwise  it  is  signed. 

SEE  ALSO 

open  (II),  creat  (II) 

DIAGNOSTICS 

The  error  bit  (c-bit)  is  set  for  an  undefined  file  descriptor.  From  C,  a 
-1  return  indicates  an  error. 
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NAME 

setgid  -  set  process  group  ID 
SYNOPSIS 

(setgid  -  46.;  not  in  assembler) 

(group  ID  in  rO) 

sys  setgid 

setgld(gld) 

DESCRIPTION 

The  group  ID  of  the  current  process  is  set  to  the  argument.  Both  the 
effective  and  the  real  group  ID  are  set.  This  call  is  only  permitted  if 
the  argument  is  the  real  group  ID. 

SEE  ALSO 

getgld  (II) 

DIAGNOSTICS 

Error  bit  (c-bit)  is  set  as  indicated;  from  C,  a  -1  value  is  returned. 

KSOS 

This  call  is  not  yet  implemented. 


SETUID(VI) 


KSOS  9/29/80 


SETUID ( VI ) 


NAME 

setuld  -  set  process  user  ID 

SYNOPSIS 

(setuld  -  23 . ) 

(user  ID  In  r0) 

sys  setuld 

setuld(uid) 

DESCRIPTION 

The  user  ID  of  the  current  process  Is  set  to  the  argument.  Both  the 
effective  and  the  real  user  ID  are  set.  This  call  Is  only  permitted  If 
the  argument  Is  the  real  user  ID. 

SEE  ALSO 

getuld  (II) 

DIAGNOSTICS 

Error  bit  (c-blt)  Is  set  as  Indicated;  from  C,  a  -1  value  is  returned. 

KSOS 

This  call  Is  not  yet  Implemented. 
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NAME 

signal  -  catch  or  Ignore  signals 

SYNOPSIS 

(signal  =  48. ) 

sya  signal;  slg;  label 

(old  value  in  r0) 

signal (slg,  func) 

Int  (*func)(  ); 

DESCRIPTION 

A  signal  Is  generated  by  some  abnormal  event,  Initiated  either  by  user  at 
a  typewriter  (quit,  interrupt),  by  a  program  error  (bus  error,  etc.),  or 
by  request  of  another  program  (kill).  Normally  all  signals  cause  termi¬ 
nation  of  the  receiving  process,  but  this  call  allows  them  either  to  be 
ignored  or  to  cause  an  interrupt  to  a  specified  location.  Here  is  the 
list  of  signals: 

1  hangup 

2  interrupt 

3*  quit 

4*  illegal  instruction  (not  reset  when  caught) 

5*  trace  trap  (not  reset  when  caught) 

6*  IOT  instruction 

7*  EMT  instruction 

8*  floating  point  exception 
9  kill  (cannot  be  caught  or  Ignored) 

10*  bus  error 

11*  segrenintion  violation 

12*  bad  argument  to  system  call 

13  write  on  a  pipe  with  no  one  to  read  it 

In  the  assembler  call,  if  label  is  0,  the  process  is  terminated  when  the 
signal  occurs;  this  is  the  default  action.  If  label  is  odd,  the  signal 
is  ignored.  Any  other  even  label  specifies  an  address  in  the  process 
where  an  Interrupt  is  simulated.  An  RTI  or  RTT  instruction  will  return 
from  the  interrupt.  Except  as  indicated,  a  signal  is  reset  to  0  after 
being  caught.  Thus  if  it  is  desired  to  catch  every  such  signal,  the 
catching  routine  must  issue  another  signal  call. 

In  C,  if  func  is  0,  the  default  action  for  signal  slg  (termination)  is 
reinstated.  If  func  is  1,  the  signal  is  ignored.  If  func  is  non-zero 
and  even,  it  is  assumed  to  be  the  address  of  a  function  entry  point. 

When  the  signal  occurs,  the  function  will  be  called.  A  return  from  the 
function  will  continue  the  process  at  the  point  it  was  interrupted.  As 
in  the  assembler  call,  signal  must  in  general  be  called  again  to  catch 
subsequent  signals. 

When  a  caught  signal  occurs  during  certain  system  calls,  the  call  ter¬ 
minates  prematurely.  In  particular  this  can  occur  during  a  read  or  write 
on  a  slow  device  (like  a  typewriter;  but  not  a  file);  and  during  sleep  or 
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wait .  When  such  a  signal  occurs,  the  saved  user  status  Is  arranged  In 
such  a  way  that  when  return  from  the  signal-catching  takes  place,  It  will 
appear  that  the  system  call  returned  a  characteristic  error  status.  The 
user's  program  may  then,  if  It  wishes,  re-execute  the  call. 


The  starred  signals  In  the  list  above  cause  a  core  Image  if  not  caught  or 
Ignored. 


The  value  of  the  call  is  the  old  action  defined  for  the  signal. 


After  a  fork  (II)  the  child  inherits  all  signals.  Exec  (II)  resets  all 
caught  signals  to  default  action. 

SEE  ALSO 

kill  (I),  kill  (II),  ptrace  (II),  reset  (III) 


DIAGNOSTICS 

The  error  bit  (c-bit)  is  set  if  the  given  signal  is  out  of  range.  In  C, 
a  -1  indicates  ar.  e.ror;  0  indicates  success. 

BUGS 
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NAME 

sleep  -  stop  execution  for  Interval 
SYNOPSIS 

(sleep  -  35.;  not  In  assembler) 

(seconds  In  rO) 

sys  sleep 

sleep(seconds) 

DESCRIPTION 

The  current  process  Is  suspended  from  execution  for  the  number  of  seconds 
specified  by  the  argument. 

SEE  ALSO 

sleep  (I) 

DIAGNOSTICS 
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NAME 

scat  -  get  file  status 

SYNOPSIS 

(stat  -  18.) 

sys  stat;  name;  buf 

stat (name,  buf) 
char  *name; 
struct  Inode  *buf; 

DESCRIPTION 

Name  points  to  a  null-terminated  string  naming  a  file;  buf  Is  the  address 
of  a  36(10)  byte  buffer  Into  which  Information  Is  placed  concerning  the 
file.  It  Is  unnecessary  to  have  any  permissions  at  all  with  respect  to 
the  file,  but  all  directories  leading  to  the  file  must  be  readable. 

After  stat ,  buf  has  the  following  structure  (starting  offset  given  in 
bytes ) : 

struct  Inode  { 


char 

minor; 

/*  -M):  minor  device  of  i-node  */ 

char 

major; 

/*  4-1 :  ma  Jor  device  */ 

int 

inumber; 

/*  4-2  */ 

Int 

flags; 

/*  4-4:  see  below  */ 

char 

nllnks; 

/*  4-6:  number  of  links  to  file  */ 

char 

uid; 

/*  4-7:  user  ID  of  owner  */ 

char 

gid; 

/*  4-8:  group  ID  of  owner  */ 

char 

slzeO; 

/*  4-9:  high  byte  of  24-blt  size  */ 

int 

sizel ; 

/*  4-10:  low  word  of  24-bit  size  */ 

l'Ut 

addr[8] ; 

/*  4-12:  block  numbers  or  device  number  */ 

int 

actime[2] ; 

/*  4-28:  time  of  last  access  */ 

int 

mod time (2 j ; 

/*  4-32:  time  of  last  modification  */ 

}; 

The  flags  are  as  follows: 

100000  i-node  Is  allocated 

060000  2-bit  file  type: 

000000  plain  file 
040000  directory 

020000  character-type  special  file 
060000  block-type  special  file. 
010000  large  file 

004000  set  user-ID  on  execution 

002000  set  group- ID  on  execution 

001000  save  text  Image  after  execution 

000400  read  (owner) 

000200  write  (owner) 

000100  execute  (owner) 

000070  read,  write,  execute  (group) 

000007  read,  write,  execute  (others) 
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SEE  ALSO 

Is  (I),  fstat  (II),  fa  (V) 

DIAGNOSTICS 

Error  bit  (c-bit)  Is  set  If  the  file  cannot  be  found.  From  C,  a  -1 
return  Indicates  an  error. 


Not  all  fields  are  meaningful  under  KSOS.  The  stat  call  supplies  zeroes 
In  such  fields,  which  are:  nllnka,  addr,  and,  actime. 
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NAME 

sclme  -  sec  time 

SYNOPSIS 

(sClme  »  25. ) 

(time  In  rO-rl) 

sys  stlme 

stime(tbuf ) 
lnt  tbuf[2]; 

DESCRIPTION 

Stlme  sets  the  system's  idea  of  the  time  and  date.  Time  Is  measured  In 
seconds  from  0000  GMT  Jan  1  1970.  Only  the  super-user  may  use  this  call. 

SEE  ALSO 

date  (I),  time  (II),  ctlme  (III) 

DIAGNOSTICS 

Error  bit  (c-bit)  set  if  user  is  not  the  super-user. 


KSOS 

This  call  has  been  subsumed  by  the  NKSR.  Attempted  use  under  the  UNIX 
Emulator  will  result  in  an  error. 


STTY(VI) 


KSOS  12/9/80 


STTY(VI) 


NAME 

stty  -  set  mode  of  typewriter 

SYNOPSIS 

(stty  =  31 . ) 

(file  descriptor  in  rO) 

sy8  stty;  arg 
•  •  • 

arg:  .byte  ispeed,  ospeed;  .byte  erase,  kill;  mode 

stty(fildes,  arg) 
struct  ( 

char  ispeed,  ospeed; 
xchar  erase,  kill; 

lnt  mode ; 

}  *arg; 


DESCRIPTION 

Stty  sets  mode  bits  and  character  speeds  for  the  typewriter  whose  file 
descriptor  is  passed  in  rO  (reap,  is  the  first  argument  to  the  call). 
First,  the  system  delays  until  the  typewriter  is  quiescent.  The  input 
and  output  speeds  are  set  from  the  first  two  bytes  of  the  argument  struc¬ 
ture  as  indicated  by  the  following  table,  which  corresponds  to  the  speeds 
supported  by  the  DH-1I  interface.  If  DC-H,  DL-I1  or  KL-11  Interfaces 
are  used,  impossible  speed  changes  are  ignored. 

0  (hang  up  dataphone) 

1  50  baud 

2  75  baud 

3  110  baud 

4  134.5  baud 

5  150  baud 

6  200  baud 

7  300  baud 

8  600  baud 

9  1200  baud 

10  1800  baud 

11  2400  baud 

12  4800  baud 

13  9600  baud 

14  External  A 

15  External  B 

In  the  current  configuration,  only  110,  150  and  300  baud  are  really  sup¬ 
ported  on  dial-up  lines,  in  that  the  code  conversion  and  line  control 
required  for  IBM  2741 's  (134.5  baud)  must  be  Implemented  by  the  user's 
program,  and  the  half-duplex  line  discipline  required  for  the  202  dataset 
(1200  baud)  is  not  supplied. 

The  next  two  characters  of  the  argument  structure  specify  the  erase  and 
kill  characters  respectively.  (Defaults  are  if  and  @.) 
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The  mode  contains  several  bits  which  determine  the  system's  treatment  of 
the  typewriter: 


100000 

040000 


03^000 

006000 

001400 

000200 

000100 

000040 

000020 

000010 

000004 

000002 

000001 


Select  one  of  two  algorithms  for  backspace  delays 

Select  one  of  two  algorithms  for  form-feed  and  vertical-tab 

delays 

Select  one  of  four  algorithms  for  carriage-return  delays 

Select  one  of  four  algorithms  for  tab  delays 

Select  one  of  four  algorithms  for  new-line  delays 

even  parity  allowed  on  input  (e.  g.  for  M37s) 

odd  parity  allowed  on  input 

raw  mode:  wake  up  on  all  characters 

map  CR  into  LF;  echo  LF  or  CR  as  CR-LF 

echo  (full  duplex)  ' 

map  upper  case  to  lower  on  input  (e.  g.  M33) 

echo  and  print  tabs  as  spaces 

hang  up  (remove  'data  terminal  ready,  '  lead  CD)  after  last 
close 


The  delay  bits  specify  how  long  transmission  stops  to  allow  for  mechani¬ 
cal  or  other  movement  when  certain  characters  are  sent  to  the  terminal. 

In  all  cases  a  value  of  0  Indicates  no  delay. 

Backspace  delays  are  currently  Ignored  but  will  be  used  for  Terminet 
300 's. 

If  a  form-feed/vertical  tab  delay  is  specified,  it  lasts  for  about  2 
seconds. 

Carriage-return  delay  type  1  lasts  about  .08  seconds  and  is  suitable  for 
the  Terminet  300.  Delay  type  2  lasts  about  .16  seconds  and  is  suitable 
for  the  VT05  and  the  TI  700.  Delay  type  3  is  unimplemented  and  is  0. 

New-line  delay  type  1  is  dependent  on  the  current  column  and  is  tuned  for 
Teletype  model  37 's.  Type  2  is  useful  for  the  VT05  and  is  about  .10 
seconds.  Type  3  is  unimplemented  and  is  0. 

Tab  delay  type  1  is  dependent  on  the  amount  of  movement  and  is  tuned  to 
the  Teletype  model  37.  Other  types  are  unimplemented  and  are  0. 

Characters  with  the  wrong  parity,  as  determined  by  bits  200  and  100,  are 
Ignored. 

In  raw  mode,  every  character  is  passed  immediately  to  the  program  without 
waiting  until  a  full  line  has  been  typed.  No  erase  or  kill  processing  is 
done;  the  end-of-file  character  (EOT),  the  interrupt  character  (DEL)  and 
the  quit  character  (FS)  are  not  treated  specially. 

Mode  020  causes  input  carriage  returns  to  be  turned  into  new-lines;  input 
of  either  CR  or  LF  causes  LF-CR  both  to  be  echoed  (used  for  GE  TermiNet 
300's  and  other  terminals  without  the  newline  function). 
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The  hangup  mode  01  causes  Che  line  Co  be  dlsconnecCed  when  Che  lasc  pro¬ 
cess  wlch  che  line  open  closes  1C  or  terminates.  It  Is  useful  when  a 
pore  Is  Co  be  used  for  some  special  purpose;  for  example,  If  1C  Is  asso- 
claCed  wlch  an  ACU  used  Co  place  ouCgolng  calls. 

This  syscem  call  Is  also  used  wlch  cerCaln  special  files  ocher  chan  type- 
wriCers,  bur  since  none  of  Chem  are  pare  of  Che  scandard  system  Che 
specifications  will  not  be  given. 

SEE  ALSO 

sety  (I),  gtty  (II) 


DIAGNOSTICS 

The  error  bit  (c-bic)  Is  set  If  Che  file  descriptor  does  not  refer  to  a 
typewriter.  From  C,  a  negative  value  Indicates  an  error. 


KSOS 

It  Is  not  possible  Co  set  speeds  or  parity  from  the  UNIX  Emulator.  In  no 
case  are  more  chan  two  delay  algorithms  available.  Hangup  mode  Is  not 
supported. 
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NAME 

sync  -  update  super-block 
SYNOPSIS 

(sync  ■  36.;  not  In  assembler) 

sys  sync 

DESCRIPTION 

Sync  causes  all  Information  In  core  memory  that  should  be  on  disk  to  be 
written  out.  This  Includes  modified  super  blocks,  modified  i-nodes,  and 
delayed  block  I/O. 

It  should  be  used  by  programs  which  examine  a  file  system,  for  example 
1 check,  df,  etc.  It  is  mandatory  before  a  boot. 


SEE  ALSO 

sync  (VIII),  update  (VIII) 
DIAGNOSTICS 

KSOS 


This  call  causes  the  Emulator  Family  buffer  cache  to  be  flushed 
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NAME 

time  -  get  date  and  time 

SYNOPSIS 

(time  “  13.) 
sys  time 

time(t vec) 
int  tvec[2); 

DESCRIPTION 

Time  returns  the  time  since  00:00:00  GMT,  Jan.  I,  1970,  measured 
seconds.  From  as,  the  high  order  word  is  in  the  rO  register  and 
order  is  in  rl.  From  C,  the  user-supplied  vector  is  filled  in. 

SEE  ALSO 

date  (I),  stime  (II),  ctime  (III) 
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in 

the  low 


DIAGNOSTICS 
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NAME 

times  -  get  process  times 
SYNOPSIS 

(times  -  43.;  not  in  assembler) 

sya  times;  buffer 

times('Duffer) 

struct  tbuffer  *buffer; 

DESCRIPTION 

Times  returns  time-accounting  information  for  the  current  process  and  for 
the  terminated  child  processes  of  the  current  process.  All  times  are  in 
1/60  seconds. 

After  the  call,  the  buffer  will  appear  as  follows: 

struct  cbuffer  { 

int  proc_user_time; 

int  proc_system_time; 

int  child_user_time[2] ; 

int  child_system_time[2 J ; 

}; 

The  children  times  are  the  sum  of  the  children's  process  times  and  their 
children's  times. 

SEE  ALSO 

t  i  me  ( I ) 

DIAGNOSTICS 


BUGS 

The  process  times  should  be  32  bits  as  well. 

KSOS 
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NAME 

umount  -  dismount  file  system 

SYNOPSIS 

(umount  -  22. ) 

ays  umount ;  special 

DESCRIPTION 

Umount  announces  to  Che  system  that  special  file  special  is  no  longer  to 
contain  a  removable  file  system.  The  file  associated  with  the  special 
file  reverts  to  its  ordinary  interpretation;  see  mount  (II). 


SEE  ALSO 

umount  (VIII),  mount  (II) 


DIAGNOSTICS 

Error  bit  (c-bit)  set  if  no  file  system  was  mounted  on  the  special  file 
or  if  there  are  still  active  files  on  the  mounted  file  system. 


K.SOS 

This  call  has  been  subsumed  by  the  NKSR.  Attempted  use  from  the  UNIX 
Emulator  will  result  in  an  error. 
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NAME 

unlink  -  remove  directory  entry 


SYNOPSIS 

(unlink  =»  10.) 

ays  unlink;  name 

unlink(name) 
char  *name ; 


DESCRIPTION 

Name  points  to  a  null-terminated  string.  Unlink  removes  the  entry  for 
the  file  pointed  to  by  name  from  its  directory.  If  this  entry  was  the 
last  link  to  the  file,  the  contents  of  the  file  are  freed  and  the  file  is 
destroyed.  If,  however,  the  file  was  open  in  any  process,  the  actual 
destruction  is  delayed  until  it  is  closed,  even  though  the  directory 
entry  has  disappeared. 


SEE  ALSO 

rm  (I),  rmdir  (I),  link  (II) 


DIAGNOSTICS 

The  error  bit  (c-bit)  is  set  to  indicate  that  the  file  does  not  exist  or 
that  Its  directory  cannot  be  written.  Write  permission  is  not  required 
on  the  file  Itself.  From  C,  a  -1  return  indicates  an  error. 
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NAME 

wale  -  wait  for  process  co  terminate 

SYNOPSIS 

(wait  “  7. ) 

ays  wait 

(process  10  In  rO) 

(status  In  rl) 

wait (status) 
int  ^status; 

DESCRIPTION 

Walt  causes  Its  caller  to  delay  until  one  of  Its  child  processes  ter¬ 
minates.  If  any  child  has  died  since  the  last  wait,  return  Is  Immediate; 
If  there  are  no  children,  return  Is  immediate  with  the  error  bit  set 
(resp.  with  a  value  of  -1  returned).  The  normal  return  yields  the  pro¬ 
cess  ID  of  the  terminated  child  (in  rO).  In  the  case  of  several  children 
several  wait  calls  are  needed  to  learn  of  all  the  deaths. 

If  no  error  is  Indicated  on  return,  the  rl  high  byte  (resp.  the  high  byte 
stored  into  status  )  contains  the  low  byte  of  the  child  process  rO  (resp. 
the  argument  of  exit  )  when  It  terminated.  The  rl  (resp.  status  )  low 
byte  contains  the  termination  status  of  the  process.  See  signal  (II)  for 
a  list  of  termination  statuses  (signals);  0  status  indicates  normal  ter¬ 
mination.  A  special  status  (0177)  is  returned  for  a  stopped  process 
which  has  not  terminated  and  can  be  restarted.  See  ptrace  (II).  If  the 
0200  bit  of  the  termination  status  Is  set,  a  core  Image  of  the  process 
was  produced  by  the  system. 

SEE  ALSO 

exit  (II),  fork  (II),  signal  (II) 

DIAGNOSTICS 

The  error  bit  (c-bit)  is  set  if  there  are  no  children  not  previously 
waited  for.  From  C,  a  returned  value  of  -I  indicates  an  error. 
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NAME 

write  -  write  on  a  file 

SYNOPSIS 

(write  “  4. ) 

(file  descriptor  In  rO) 
sys  write;  buffer;  nbytes 

write(fildes,  buffer,  nbytes) 
char  *buffer; 

DESCRIPTION 

A  file  descriptor  Is  a  word  returned  from  a  successful  open,  craat ,  dap, 
pipe,  or  port  call. 

Buffer  is  the  address  of  nbytes  contiguous  bytes  which  are  written  on  the 
output  file.  The  number  of  characters  actually  written  is  returned  (in 
rO).  It  should  be  regarded  as  an  error  if  this  is  not  the  same  as 
requested. 

Writes  which  are  multiples  of  512  characters  long  and  begin  on  a  512-byte 
boundary  in  the  file  are  more  efficient  than  any  others. 

SEE  ALSO 

creat  (II),  open  (II),  pipe  (II),  eofp  (II) 

DIAGNOSTICS 

The  error  bit  (c-bit)  is  set  on  an  error:  bad  descriptor,  buffer  address, 
or  count;  physical  I/O  errors.  From  C,  a  returned  value  of  -1  indicates 
an  error. 
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